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MANUAL OBJECTIVES 

This manual is a guide to the use of RMS-11 in programs written in 
MACRO-11. It contains information necessary to writing MACRO-11 
programs and subprograms that use RMS-11 operations. 



INTENDED AUDIENCE 

This manual is intended for both the MACRO-11 programmer who wants to 
use RMS-11 operations and the high-level language programmer who wants 
to use RMS-11 operations in a MACRO-11 subprogram. 



STRUCTURE OF THIS DOCUMENT 

• Chapter 1, Introduction to RMS-11 with MACRO-11, introduces 
RMS-11 macros and symbols that are the interface between a 
MACRO-11 program and RMS-11 operation routines. 

• Chapter 2, RMS-11 Programming in MACRO-11, shows how to use 
RMS-11 macros and symbols in a MACRO-11 program. 

• Chapter 3, Processing Directories and Files, shows how to use 
directory and file operations to process directories and 
f i les . 

• Chapter 4, Processing Records and Blocks, shows how to use 
stream operations and either record or block operations to 
process records or blocks. 

• Chapter 5, Operation Macro Descriptions, describes in detail 
each RMS-11 operation macro, the control blocks it uses, the 
options you can specify in each control block field, and the 
values returned in control block fields. 

• Chapter 6, Control Block Fields, summarizes the use of each 
control block, field, value, and mask. 

• Chapter 7, Example Programs, contains programs and program 
segments that illustrate the uses of some major RMS-11 
features . 
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• Appendix A, Completion Codes and Fatal Error Codes, lists 
RMS-11 completion symbols, values, and meanings. 

• Appendix B, Assembly-Time Messages, lists the messages that 
RMS-11 macros can generate at assembly time. 

• Appendix C, Macros That Declare Symbols and Other Macros, 
describes RMS-11 macros that declare other RMS-11 macros and 
define RMS-11 symbols. 

• Appendix D, RMS-11 with Different Operating Systems, 
describes the differences among the behaviors of RMS-11 with 
various operating systems. 

• The index includes a major entry for each RMS-11 macro, 
control block field mnemonic, keyword macro argument, and 
symbol family. 



ASSOCIATED DOCUMENTS 

RSX -1 1M/M-PLUS RMS-11 : An Introduction introduces the major concepts 
of RMS-11, introduces the RMS-11 operations, and defines key terms 
required for understanding RMS-11 capabilities and functions. You 
should read the introduction before proceeding to other manuals in the 
RMS-11 documentation set. 

The RSX-11M/M-PLUS RMS-11 User ' s Guide provides detailed information 
for both MACRO-11 and high-level language programmers on file and task 
design using RMS-11. 

The RSX-11M/M-PLUS RMS-11 Utilities manual is both a user and a 
reference document for all users, both programmers and nonprogrammer s . 
It describes the RMS-11 utilities that are available for creating and 
maintaining RMS-11 files. 

In addition, the RSX-11M/M-PLUS RMS-11 Mini-Reference Insert is an 
easy-reference guide for users who are familiar with RMS-11 and its 
documentation. It summarizes the RMS-11 utilities and error codes. 



CONVENTIONS USED IN THIS DOCUMENT 

The following conventions are used in statement formats in this 
document : 

UPPERCASE Uppercase characters within a string indicate 

characters that you must include in the string; you 
can type the characters in uppercase or lowercase. 

lowercase Lowercase characters within a string indicate a 

user-selected variable; text following the 

statement format defines the syntax of the variable. 

[ ] Square brackets indicate that the enclosed string is 

optional user input. 

... A horizontal ellipsis indicates that the immediately 

preceding optional string (enclosed in square 
brackets) may be repeated. 



PREFACE 



From: DES.TMP In examples of commands you enter and system 
responses, all output lines and prompting characters 
that the system prints or displays are shown in 
black letters. All the lines you type are shown in 
red letters. 

other A nonalphabet ic character (except a square bracket 

or a period that is part of an ellipsis) indicates a 
character that you must include in the string. 



Numbers in this manual that give the values of RMS-11 symbols are in 
octal radix (base 8) unless otherwise indicated; all other numbers in 
this manual are in decimal radix (base 10). 



SUMMARY OF TECHNICAL CHANGES 



This revision contains the following technical changes: 

• The new operation macros $ENTER, $PARSE , $REMOVE, $ RENAME , 
and $SEARCH are documented, along with the related NAM block 
fields FNB, RSA, RSL , and RSS. 

• The new facility for wildcard file specification is 
documented . 

• The extension of access sharing is documented, along with the 
related masks FB$UPI and FB$NI L for the SHR field of the FAB. 

• Random access to a sequential file with fixed-length records 
(similar to random access to a relative file) is documented. 

• The new print-format record-output handling is documented, 
along with the related symbol FB$PRN for the RAT field of the 
FAB. 

• The new sequential block access is documented; the previous 
block access (formerly called block I/O) is now called VBN 
access (virtual block number access) . 

• Block access can now be used to copy RMS-11 files without the 
need to modify the file's attributes manually. 

• The addition of the success handler facility for file 
operation macros ($CLOSE, $CREATE, $DISPLAY, $ERASE, $EXTEND, 
and $OPEN) is documented. 

• Increased device transparency for record access copy 
operations is supported. VFC and stream record formats are 
supported on unit-record devices. Relative and indexed files 
can be created for record access on nondisk devices, although 
they will appear as and be processed as sequential files 
there . 

• The obsolete RMS-11 initialization macros $INIT and $INITIF 
are no longer documented. These macros are now defined as 
no-ops in the RMS-11 macro library RMSMAC.MLB; their 
previous functions are no longer needed because RMS-11 is now 
sel f- ini t ial i zing . However, programs that use the $INIT and 
$INITIF macros in their previous senses remain valid under 
RMS-11 Version 2.0. 
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SUMMARY OF TECHNICAL CHANGES 



• Each XAB type now has a distinct name; the following are the 
new names: 



ALL block Area 

DAT block File 

KEY block File 

PRO block File 

SUM block File 



allocation XAB 
date XAB 
key XAB 

protection XAB 
summary XAB 



• The following symbol declaration macros are documented: 



FAB$BT 


Declare 


FAB 


val ue 


and mask 


symbols 


NAM$BT 


Declare 


NAM 


block 


value and 


mask symbols 


RAB$BT 


Declare 


RAB 


val ue 


and mask 


symbols 


XAB$BT 


Dec lare 


XAB 


value 


and mask 


symbol s 


XBAOF$ 


Declare 


ALL 


block 


symbols 




XBDOF$ 


Declare 


DAT 


block 


symbol s 




XBKOF$ 


Declare 


KEY 


block 


symbol s 




XBPOF$ 


Dec lare 


PRO 


block 


symbol s 




XBSOF$ 


Declare 


SUM 


block 


symbols 




descr i pt i on 


of each 


opera ti on 


macro includes the use 



meaning of each associated control block field. 

• The value of each RMS-11 user symbol is documented. 

• The structure of each RMS-11 user control block is 
documented . 



• The FAB has a new LRL (longest record length) field for 
sequential files (corresponding to the VAX-11 RMS XAB LRL 
field) . 

• The date/time XABs have changed in size from 36 to 46 octal 
bytes . 

• For ANSI magtape, RMS-11 allows fixed-format records to be 
less than 18 bytes. 

• <CTRL/Z> and <ESC> are no longer recognized as record 
terminators for stream files; and <CTRL/Z> is no longer 
recognized as a file terminator for stream files. 

• RMS-11 now pads stream files with null characters to the high 
block of the file (not just to the end of the current block) . 
This means that RMS-1 1-crea ted stream files can be read by 
programs that do not recognize the EOF value from the file 
header . 
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CHAPTER 1 



INTRODUCTION TO RMS-11 WITH MACRO-11 



RMS-11 macros and symbols provide access to RMS-11 operations from a 
MACRO-11 program. 



1.1 ADVANTAGES OF USING RMS-11 MACROS 

When you use RMS-11 operations from a high-level language, the 
language restricts your options for some operations. If you cannot 
accept these restrictions, you can write your program (or some of its 
modules) in MACRO-11; this allows you full access to RMS-11 options. 



1.2 RMS-11 MACROS AND SYMBOLS 

RMS-11 macros and symbols define the interface between a MACRO-11 
program and RMS-11 operation routines. Definitions for these macros 
and symbols are in the RMS-11 macro library, RMSMAC . MLB . 

RMS-11 macros allow your program to: 

• Call RMS-11 operations 

• Declare and manipulate control blocks, through which your 
program communicates with RMS-11 operation routines 

• Declare and manipulate space pools 

• Declare needed RMS-11 facilities 

• Extract (from the macro library RMSMAC. MLB) definitions for 
RMS-11 macros and symbols 

The following sections introduce RMS-11 macros and symbols. 
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1.2.1 Operations 



An RMS-11 operation macro calls 
operation. The name of an 
corresponding operation, with 
following are the RMS-11 operation macros: 



a routine that performs an RMS-11 
operation macro is the name of the 
a prefixed dollar sign ($) . The 



Directory 
Operation 
Macros 



File 

Operation 
Macros 



Stream 

Operation 

Macros 



Record 

Operation 

Macros 



Block 

Operation 

Macros 



$ENTER $CLOSE $CONNECT $DELETE $READ 

$PARSE $CREATE $DISCONNECT $FIND $SPACE 

$REMOVE $DISPLAY $FLUSH $GET $WRITE 

$ RENAME $ERASE $FREE $PUT 

$SEARCH $EXTEND $NXTVOL $TRUNCATE 

$OPEN $REWIND $UPDATE 
$WAIT 



An RMS-11 operation returns a value called a completion code that 
indicates either a successful operation or an error. RMS-11 
completion symbols give names to these completion codes. 

When your program uses an RMS-11 operation macro to call an operation 
routine, it can specify completion handlers (one for a successful 
completion, one for an error completion) that RMS-11 calls when the 
operation completes. The RMS-11 completion-return macro ($RETURN) 
generates a proper return from a completion handler to the calling 
point in your program. 



1.2.2 Control Blocks and Fields 

Your program and RMS-11 operation routines communicate by passing data 
in blocks called control blocks. Each control block is divided into 
fields; each field has a 3-letter mnemonic name. 

An RMS-11 block-declaration macro allocates space for a control block 
and initializes fields containing the block length and block 
identifier. There is a block-declaration macro for each kind of 
control block. 

An RMS-11 field-initialization macro sets an initial value for a 
control block field at assembly time. There are field-initialization 
macros for most control block fields (those that you might reasonably 
want to initialize). 

An RMS-11 field-access macro manipulates the value of a control block 
fie?ld during program execution. There are field-access macros for 
copying values to and from fields ($STORE and $FETCH) , for comparing 
field values with other values ($COMPARE), and for setting, clearing, 
and testing bits in fields ($SET, $OFF, and $TESTB ITS ) . 

RMS-11 code and mask symbols give names to the codes and bit masks 
used in many fields. This allows your program to determine the 
details of an RMS-11 operation without using the numeric values 
associated with those details. 

RMS-11 field-offset symbols give names to the locations of fields 
within their control blocks. Because RMS-11 field-initialization and 
field-access macros are based on field names, your program need not 
use field-offset symbols. 
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RMS-11 control blocks and their general uses are as follows: 

• ALL (area allocation) block - contains information about a 
file area. 

• DAT (file date) block - contains file dates and the file 
revision number. 

• FAB (file access block) - contains general information about a 
file and how a program will access it. 

• KEY (file key) block - contains information about a file index 
and its key. 

• NAM (file name) block - contains special information about the 
device, directory, and specification for the file, along with 
wildcarding information. 

• PRO (file protection) block - contains file owner and 
protection information. 

• RAB (record access block) - contains general information about 
a stream and a record or block, and how the program accesses 
the record or block. 

• SUM (file summary) block - contains the number of areas and 
indexes in the file, and a version number indicating the 
internal structure level of the file. 



1.2.3 Pools 

RMS-11 conserves space by dynamically allocating and deallocating 
space set aside in pools. RMS-11 pool-declaration macros allocate 
space for pools. 

An RMS-11 routine called the get-space routine handles pooled space. 
You can substitute your own get-space routine for the RMS-11 routine; 
you can use RMS-11 get-space-address macros to initialize the address 
of the get-space routine at assembly time (GSA$) , to change the 
address to that of a different routine during program execution 
($SETGSA) , and to return the address of the current routine during 
program execution ($GETGSA) . 



1.2.4 Facilities 

The RMS-11 facilities-declaration macro (ORG$) assists RMS-11 in 
determining exactly which routines your program needs during program 
execution . 



1.2.5 Macros That Declare Symbols and Other Macros 

To extract the definition of an RMS-11 macro from the macro library, 
your program must declare the macro in a .MCALL assembler directive. 

Many RMS-11 macros declare related macros and define related symbols; 
some RMS-11 macros have the sole purpose of declaring related macros 
and defining related symbols. Using these macros simplifies the job 
of declaring macros and defining symbols in your program. 
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For example, the FAB-declarat i on macro FAB$B declares FAB 
field-initialization macros and FAB offset, code, and mask symbols; 
the $FBCAL macro declares all directory and file operation macros; 
the $RMSTAT macro declares all completion symbols. 



1-4 



CHAPTER 2 



RMS- 11 PROGRAMMING 



To use RMS-11 operations in a MACRO-11 program, your program must: 

• Declare RMS-11 macros and symbols 

Before your program refers to an RMS-11 macro or symbol, it 
must extract its definition from the RMS-11 macro library. 
Section 2.1 shows how to declare macros and symbols. 

• Declare RMS-11 facilities 

To help RMS-11 decide which RMS-11 program modules are needed 
for your program, your program must declare some of the RMS-11 
operations that it uses. Section 2.2 shows how to declare 
RMS-11 facilities. 

• Declare and use pool space 

RMS-11 dynamically allocates and deallocates space for some of 
its requirements; this space is separated into five pools. 
Using RMS-11 pool-declaration macros, you specify the size of 
each pool. Section 2.3 shows how to declare pool space. 

• Declare and initialize control blocks 

Your program and RMS-11 operation routines communicate by 
passing data back and forth in control block fields. Using 
RMS-11 block-declaration and field-initialization macros, your 
program allocates space for control blocks and (optionally) 
assigns initial values for fields. Section 2.4 shows how to 
declare and initialize control blocks. 

• Use RMS-11 operations 

Your program uses RMS-11 operation routines to perform record 
management services; the routines return values that show the 
results of the operations. Your program uses RMS-11 operation 
macros to call these operation routines. Section 2.5 shows 
how to call RMS-11 operation routines and how to handle 
returns from the routines. 

Your program may also: 

• Include completion handlers 

An RMS-11 operation routine returns either a success 
completion code or an error completion code. Your program can 
include special routines (called success handlers and error 
handlers) that operation routines call automatically when 
operations complete. Section 2.6 shows how to write 
completion handlers. 
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• Use its own get-space routines 

RMS-11 uses a routine (called a get-space routine) to allocate 
and deallocate space. RMS-11 has a get-space routine, but you 
can also supply others of your own. Section 2.7 shows how to 
use get-space routines and how to write a get-space routine. 

Finally, you must: 

• Assemble the program 

When you assemble your program, it needs macro and symbol 
definitions from RMS-11; these are in a macro library, which 
your assembler command line must reference. RMS-11 macros 
detect some kinds of errors during assembly, and print 
messages that identify the errors. Section 2.8 shows how to 
assemble your program. 

• Build the task 

When you build your task, you must do one of the following: 
Use an RMS-11 resident library. 

Define an overlay structure for the task. RMS-11 offers 
several overlay definition (ODL) files from which you can 
select; you can also write your own ODL files. 

Include RMS-11 code in the task. 



2.1 DECLARING RMS-11 MACROS AND SYMBOLS 

Before your program refers to an RMS-11 macro or symbol, it must 
extract its definition from the RMS-11 macro library. 

Your program can use the .MCALL assembler directive to extract the 
definition of any RMS-11 macro (but not a symbol) from the macro 
library. For example, to extract the definition of the macro $CLOSE, 
use the . MCALL directive in the format: 

.MCALL $CLOSE ;Declare RMS-11 $CLOSE macro 

Your program can use RMS-11 macros to extract definitions for RMS-11 
symbols, and for some groups of other RMS-11 macros. Appendix C lists 
RMS-11 macros (with their arguments) that declare symbols and other 
macros . 



2.2 DECLARING RMS-11 FACILITIES 

To help RMS-11 decide which RMS-11 program modules your program needs, 
your program declares some of the operations that it uses. To do 
this, it uses the facilities-declaration macro ORG$ in the format: 

.MCALL ORG$ ;Declare ORG$ macro 

ORG$ fileorg [ ,<operation [, operation] ...>] 

where fileorg is a keyword indicating a file organization and each 
operation is a keyword indicating an operation that your program uses 
for a file of that organization. 
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A separate ORG$ macro is required for each different file organization 
that your program processes, except that no ORG$ macro is required for 
an organization that will be processed using only directory operations 
and block access. 

The fileorg keyword argument to the ORG$ macro is one of the 
following : 

IDX Indexed file organization 

REL Relative file organization 

SEQ Sequential file organization 

Each operation argument to an ORG$ macro is one of the following: 

CRE CREATE operation 

DEL DELETE operation 

FIN FIND operation 

GET GET operation 

PUT PUT operation 

UPD UPDATE operation 

These are the only operations that your program explicitly declares 
with the ORG$ macro; support for other operations is handled 
automatically. 

For example, suppose that your program: 

• Creates both sequential and indexed files 

• Uses FIND, GET, PUT, and UPDATE operations for sequential 
f i les 

• Uses FIND, GET, PUT, and DELETE operations for indexed files 
Then the proper ORG$ macros are: 



ORG$ SEQ,<FIN,GET,PUT,UPD> 
ORG$ IDX,<FIN,GET,PUT,DEL> 



Declare FIND, GET, PUT, and UPDATE 
operations for sequential files 

Declare FIND, GET, PUT, and DELETE 
operations for indexed files 



The results of ORG$ macros are additive. For example, if one portion 
of your program specifies 

ORG$ SEQ,<GET,PUT> 
and another specifies 

ORG$ SEQ,<GET,UPD> 
then the effect is the same as specifying 

ORG$ SEQ,<GET,PUT,UPD> 

Note also that all ORG$ macros must occur in modules that are 
contained in the root segment of your task (not overlaid) . Use of 
ORG$ macros is optional in tasks linked with an RMS-11 memory-resident 
library. 
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2.3 DECLARING AND USING POOL SPACE 



RMS-11 dynamically allocates and deallocates space for some of its 
requirements; this space is separated into five pools: 

Internal FAB and index descriptor block (IFAB/IDB) pool 

Internal RAB (IRAB) pool 

Key buffer pool 

I/O buffer pool 

Buffer descriptor block (BDB) pool 

RMS-11 has a get-space routine that manages these pools, and that 
allocates and deallocates space to meet the needs of RMS-11 
operations; however, you can supply other get-space routines and 
direct RMS-11 to use a different routine (and, optionally, different 
pools) instead of its own. 

If you use only the RMS-11 get-space routine, declare pool space using 
the pool-declaration macros described below. If you use your own 
get-space routine, read Section 2.7; it shows how to write the 
routine, and how to manage the pools. 

To declare space for pools, use pool-declaration macros in the format: 



POOL$B 
P$FAB 
P$ IDX 
P$ RAB 



P$RABX 



Begin pool declarations 
fabcount ;Space for IFABs in IFAB/IDB pool 

indexcount ;Space for IDBs in IFAB/IDB pool 

rabcount ;Space for IRABs for sequential 

and relative files and for 
block-accessed indexed files 
in IRAB pool 

rabxcount , keys i ze , keychanges ;Space for IRABs for 

record-accessed indexed 
files in IRAB pool, and 
space for key buffers in 
key buffer pool 
Space for I/O buffers in I/O 
buffer pool 

bdbcount ;Space for BDBs in BDB pool 

End pool declarations 



P$BUF bufcount 



P $ B D B 
POOL$E 



If your program uses multiple pool declarations, 
cumulat i ve . 



the results 



are 



The following sections show how to compute the values of arguments 
the pool-declaration macros. 



to 



2-4 



RMS-11 PROGRAMMING 



2.3.1 Internal FAB and Index Descriptor Block Pool 

Internal FABs (IFABs) and index descriptor blocks (IDBs) are the same 
size and so share a pool (the IFAB/IDB pool) . The total size of the 
pool is the sum of the following: 

• The largest number of IFABs that your program uses at the same 
time, times 48 bytes. Specify this largest number of IFABs 
(not multiplied by 48) as the fabcount argument to the P$FAB 
macro . 

A directory operation uses one IFAB , which is returned to the 
pool before the operation completes. 

A CREATE or OPEN operation uses one IFAB , which is committed 
while the file is open; a CLOSE operation releases the IFAB. 
A DISPLAY or EXTEND operation uses no new IFABs; it uses the 
IFAB already committed to the open file. An ERASE operation 
uses one IFAB, which is released before the operation 
completes . 

• The largest number of IDBs that your program uses at the same 
time, times 48 bytes. Specify this largest number of IDBs 
(not multiplied by 48) as the indexcount argument to the P$IDX 
macro . 

Your program uses one IDB for each index of each indexed file 
opened for record access (rather than block access) . The IDBs 
for an indexed file are committed when the file is opened (by 
a CREATE or OPEN operation) and are released when the file is 
closed (by a CLOSE operation) . 



2.3.2 Internal RAB Pool 

Internal record access blocks (IRABs) have a separate pool. The size 
of the IRAB pool is the largest number of streams that your program 
will have connected at the same time, times the size of an IRAB (32 
bytes) . 

Specify the largest number of streams connected to sequential files, 
relative files, and block-access indexed files (not multiplied by 32) 
as the rabcount argument to the P$RAB macro. Specify the largest 
number of streams connected to record-access indexed files as the 
rabxcount argument to the P$RABX macro. 

If the sum of the rabcount and rabxcount arguments is larger than the 
largest number of streams that will ever be connected simultaneously, 
you may deduct the excess from the rabcount argument that you specify. 

An IRAB is committed when a stream is connected and is released when 
the stream is disconnected or the file is closed (using the associated 
FAB) . 
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2.3.3 Key Buffer Pool 

Key buffers have a separate pool. (These key buffers are different 
from those specified by the KBF and KSZ fields of the RAB . ) 

Each time a stream is connected to an indexed file (for record 
access) , the CONNECT operation requests space from the key buffer 
pool; the space is released when the stream is disconnected or the 
file is closed. 

Compute the size (in bytes) of the request that the CONNECT operation 
makes as follows: 

1. Begin with the size of the largest key for the file. 

2. Multiply by 2. 

3. Add the number of alternate keys for the file that are 
allowed to change during updating. 

4. Add 1. 

5. Round up (if necessary) to a multiple of 4. 

If your program performs complex sequences of CONNECT and DISCONNECT 
(or CLOSE) operations for record-access indexed files with different 
key sizes, the key buffer pool may become fragmented (and therefore 
contain unusable space). In this case, the total size of the key 
buffer pool should be larger than the sum of the requirements for each 
connected stream. 

Each P$RABX macro that your program uses (in the format P$RABX 
rabxcount ,keysi ze ,keychanges) allocates a number of bytes for the key 
buffer pool that is equal to 

(rabxcount) x ((keysize * 2) + keychanges + 1) 

The expression ((keysize * 2) + keychanges + 1) is rounded up (if 
necessary) to a multiple of 4. 

You can use P$RABX macros to precisely tailor the size of the key 
buffer pool, or to provide extra space against possible fragmentation 
problems. A good compromise is to choose the arguments to the P$RABX 
macro as follows: 

• Choose rabxcount as the largest number of streams that will be 
connected to record-access indexed files. 

• Choose keysize as the largest key in any file that will be 
processed . 

• Choose keychanges as the maximum number of changeable keys in 
any file that will be processed. 



2.3.4 I/O Buffer Pool 

The I/O buffers for RMS-11 operations come either from the central 
buffer pool or from a private buffer pool. (These are RMS-11 internal 
I/O buffers, and are different from the I/O buffers specified in the 
RBF, RSZ, UBF, and USZ fields of the RAB.) 
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Your program can specify a private buffer pool for a directory or file 
operation (except CLOSE, DISPLAY, or EXTEND) . If your program does 
not specify a private buffer pool, these operations use the central 
buffer pool. 

All other operations that require I/O buffers use the same pool as the 
CREATE or OPEN operation that opened the file. 

The minimum size of the central I/O buffer pool is the sum of the 
sizes of the I/O buffers that your program will need from it at the 
same time (ignoring I/O buffers supplied from private buffer pools) . 
Specify the size (in bytes) of the central buffer pool as the 
iopoolsize argument to the P$BUF macro. 

Specify the size (in bytes) of a private buffer pool for an operation 
in the 1-word BPS field of the FAB and the address in the 1-word BPA 
field of the FAB. If your program specifies a private buffer pool for 
a CREATE or OPEN operation, the entire pool is reserved for and 
managed by that file until the file is closed. 

Your program needs space from buffer pools for the following: 

• One 512-byte I/O buffer for any directory or file operation 
(except CLOSE, DISPLAY, or EXTEND) . This space is released 
before the operation completes. 

• One 512-byte I/O buffer for a DISPLAY or EXTEND operation for 
a record-access relative or indexed file; the space is 
returned when the operation completes. 

• I/O buffers for a CONNECT operation: 

One I/O buffer for a record-access stream connected to a 
sequential disk file. The I/O buffer uses 512 bytes times 
the multiblock count for the stream. 

One I/O buffer for a record-access stream connected to a 
sequential magtape file. The number of bytes in the I/O 
buffer is the block size for the file, rounded up (if 
necessary) to a multiple of 4 bytes. 

One I/O buffer for a record-access stream connected to a 
file on a unit-record device. The number of bytes in the 
I/O buffer is equal to the default block size for the 
device, rounded up (if necessary) to a multiple of 4 bytes. 

One or more I/O buffers for a stream connected to a 
relative file. Each I/O buffer uses 512 bytes times the 
bucket size for the file. If you use the multibuffer count 
to specify additional buffers, the requirement increases 
accordingly. 

Two or more I/O buffers for a stream connected to an 
indexed file. Each I/O buffer uses 512 bytes times the 
bucket size for the file. If you use the multibuffer count 
to specify additional buffers, the requirement increases 
accordingly. 

I/O buffers for a connected stream are retained until the 
stream is disconnected by a DISCONNECT or CLOSE operation. 
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If your program uses the I/O buffer pool for complex sequences of 
operations that use I/O buffers for different files, the pool may 
become fragmented. In that case, you may want to either allocate 
extra space in the I/O buffer pool, or limit fragmentation through the 
judicious use of private buffer pools. 



2.3.5 Buffer Descriptor Block Pool 

Your program requires one 20-byte buffer descriptor block (BDB) for 
each I/O buffer (whether from the central or a private pool) that it 
uses at the same time; these BDBs are allocated and returned at the 
same time as their associated I/O buffers. (I/O buffer requirements 
are described in the previous section.) 

In addition, a block-access stream (for any file) or a record-access 
stream that will write to a relative file requires an additional BDB; 
a record-access stream that will write to an indexed file requires two 
additional BDBs. These BDBs are returned when the stream is 
disconnected (or the file is closed). 

An EXTEND operation for a record-access relative or indexed file also 
requires an additional BDB, which is returned when the operation 
completes . 

Therefore the size of the BDB pool is the largest number of BDBs 
required at any one time, times 20 bytes. Specify this largest number 
of BDBs (not multiplied by 20) as the bdbcount argument to the P$BDB 
macro . 



2.4 DECLARING AND INITIALIZING CONTROL BLOCKS 

Your program and RMS-11 operation routines communicate by passing data 
back and forth in control block fields. Using RMS-11 
block-declaration and field-initialization macros, you allocate space 
for control blocks and (optionally) assign initial values for fields. 

To declare a control block and initialize its fields, use 
block-declaration and field-initialization macros as follows: 

1. Make sure the control block is word-aligned by using the 



2. Specify a label so that your program can refer symbolically 
to the address of the control block. 



3. Begin the block declaration with one of the following macros: 



. EVEN directive: 



.EVEN 



;Word-align block 



label : 



FAB$B 
NAM$B 
RAB$B 



;Begin FAB declaration 



SYN 



;Begin NAM block declaration 
;Begin RAB declaration for 



synchronous RAB 



RAB$B 



ASYN 



;Begin RAB declaration for 



asynchronous RAB 



XAB$B 
XAB$B 
XAB$B 
XAB$B 
XAB$B 



XB$ALL 
XB$DAT 
XB$KEY 
XB$PRO 
XB$SUM 



;Begin ALL block declaration 
;Begin DAT block declaration 
;Begin KEY block declaration 
;Begin PRO block declaration 
;Begin SUM block declaration 
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Initialize (optionally) fields with 
macros of one of the forms : 



field-initialization 



F$f Id 
N$f Id 
R$f Id 
X$f Id 



arg 
arg 
arg 
arg 



;Initialize FAB field 

;Initialize NAM block field 

;Initialize RAB field 

;Initialize XAB field 



In each of these forms, fid is the mnemonic for a field in 
the control block; arg is an argument suitable for the value 
of the field. Chapter 6 describes field-initialization 
macros and their arguments. 

End the block declaration with one of the following macros: 



FAB$E 
NAM$E 
RAB$E 
XAB$E 



;End FAB declaration 

;End NAM block declaration 

;End RAB declaration 

;End XAB declaration 



2.5 USING RMS-11 OPERATIONS 

Your program uses RMS-11 operation routines to perform record 
management services. Using RMS-11 operation macros, you call these 
operation routines. The routines return values in control block 
fields that show the results of the operations. 

To use RMS-11 operation routines, your program must: 

• Set up control block fields 

The values that your program places in control block fields 
specify the details of the service you want from the RMS-11 
operation routine. Section 2.5.1 shows how to set up control 
block fields. 

• Chain control blocks 

Some RMS-11 operation routines (stream, record, and block 
operation routines) read only RAB fields; others (directory 
and file operation routines) read FAB fields and, if your 
program supplies them, fields in NAM blocks and XABs . Your 
program chains these blocks (using address pointers) so that 
the operation routine can find them. Section 2.5.2 shows how 
to chain control blocks. 

• Call operation routines 

You use RMS-11 operation macros to call RMS-11 operation 
routines. Section 2.5.3 shows how to call operation routines. 

• Handle returns 

Section 2.5.4 shows how to handle returns from operation 
routines . 

• Examine returned values 

When an RMS-11 operation routine completes its execution, it 
has placed values in control block fields that show the 
results of the operation. Your program should examine these 
values to determine the results. Section 2.5.5 shows how to 
examine returned values. 
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2.5.1 Setting Up Control Block Fields 

The values that your program places into control block fields specify 
the details of the service you want from the RMS-11 operation routine. 
The description of each operation macro in Chapter 5 discusses the 
control block fields that are read by that operation. 

Three RMS-11 field-access macros help you place values into control 
block fields: 

• $STORE places a specified value into a field. 

• $SET sets bits in a field. 

• $OFF clears bits in a field. 



2.5.1.1 $STORE Macro - Use the $STORE macro to copy a value from a 
specified location to a control block field. The format for the 
$STORE macro is : 

$STORE src,fld,reg 

where src is a an address in memory; fid is a field mnemonic; and 
reg is a general purpose register (RO through R5) containing the 
address of the control block. 

The $STORE macro looks up the size of the destination field, so that 
it can copy the correct number of bytes or words. If the source is a 
register and the destination is a 1-byte field, then the low byte of 
the register is copied; if the source is a register and the 
destination is a multiword field, then the contents of the specified 
register and following registers are copied. 

The $STORE macro generates an error during assembly if you use an 
illegal address mode for the source. For multiword fields, illegal 
address modes are autoincrement deferred, autodecrement deferred, and 
indexed deferred. 

It is also illegal to specify the program counter (PC) as the source 
or to specify a register as source in such a way that the source 
overlaps the register that contains the control block address. 

At execution time, the $STORE macro copies the contents of the 
specified location to the control block field. The number of bytes or 
words copied is the same as the field size for the mnemonic. Chapter 
6 gives the size of each control block field. 

For example, suppose that you want to specify indexed file 
organization in the FAB for a file, and suppose that the address of 
that FAB is stored in register R2. Then the proper macro is: 

$STORE #FB$IDX,0RG,R2 ; Indexed file organization 

Suppose that you want to chain a NAM block whose label is NAMBLK to 
the same FAB. Then the proper macro is: 

$STORE #NAMBLK , NAM , R2 ; Chain NAM block 
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Suppose that you want to set the allocation quantity (ALQ field) of 
the same FAB to the value stored in a location labeled ALQVAL . Then 
the proper macro is: 

$STORE ALQVAL , ALQ , R2 ;Load allocation quantity 

and (because ALQ is a 2-word field) two words are copied from ALQVAL 
to the ALQ field. 



2.5.1.2 $SET Macro - Use the $SET macro to set bits in a 1-byte or 
1-word control block field. The $SET macro logically ORs a given mask 
into the control block field. Therefore for each bit set in the mask, 
the $SET macro sets the corresponding bit in the field; the other 
bits are not changed. 

Note that you use the $SET macro only if you want to leave some bits 
in a field undisturbed; if you want to set specified bits and clear 
all others, use the $STORE macro. 

The format for the $SET macro is: 

$SET mask, fid, reg 

where mask is an address in memory containing bits to be set; fid is 
the mnemonic for a control block field; and reg is a general purpose 
register (RO through R5) containing the address of the control block. 

If the field is not a 1-byte or 1-word field, the $SET macro generates 
an error during assembly. 

RMS-11 has symbols for masks for each bit-oriented control block 
field. Therefore your program can use these symbols instead of 
numerical values. 

For example, suppose you want to specify rewind-on-close in the FAB 
for a file, but do not want to disturb other bits in the FOP field of 
the FAB; suppose also that the address of the FAB is in register R2. 
Then the proper macro is: 

$SET #FB$RWC,F0P,R2 ; Rewi nd-on-close 

As another example, suppose you want to specify key-duplicates-allowed 
and key-changes-allowed for an index, but do not want to disturb other 
bits in the FLG field of the KEY block; suppose also that the address 
of the KEY block is in register R4 . Then the proper macro is: 

$SET #XB$DUP!XB$CHG,FLG,R4 ;Allow key duplicates and changes 



2.5.1.3 $OFF Macro - Use the $OFF macro to clear bits in a 1-byte or 
1-word control block field. The $OFF macro logically ANDs the l's 
complement of a given mask into the control block field. Therefore 
for each bit set in the mask, it clears the corresponding bit in the 
field; the other bits are not changed. 

Note that you use the $OFF macro only if you want to leave some bits 
in a field undisturbed; if you want to clear the entire field, use 
the $STORE macro (with a source value of #0) . 
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The format for the $OFF macro is: 
$OFF mask, fid, reg 

where mask is an address in memory containing bits to be cleared; fid 
is the mnemonic for a control block field; and reg is a general 
purpose register (RO through R5) containing the address of the control 
block . 

If the field is not a 1-byte or 1-word field, the $OFF macro generates 
an error during assembly. 

RMS--11 has symbols for masks for each bit-oriented control block 
field. Therefore your program can use these symbols instead of 
numerical values. 

For example, suppose you want to specify no-rewind-on-close in the FAB 
for a file, but do not want to disturb other bits in the FOP field of 
the FAB; suppose also that the address of the FAB is in register R2. 
Then the proper macro is: 

$OFF #FB$RWC,F0P,R2 ; No rewind-on-close 

As another example, suppose you want to specify 

no-key-duplicates-allowed and no-key-changes-allowed for an index, but 
do not want to disturb other bits in the FLG field of the KEY block; 
suppose also that the address of the KEY block is in register R4 . 
Then the proper macro is: 

$OFF #XB$DUP!XB$CHG,FLG,R4 ; No key duplicates or changes 



2.5.2 Chaining Control Blocks 

An RMS-11 directory operation or file operation uses at least one FAB; 
you specify FABs in the operation macros that call the operation 
rout i nes . 

For some directory operations, a NAM block is required; it is 
optional for other directory operations and for file operations. You 
specify a NAM block and XABs for an operation by chaining them to the 
FAB for the operation. 



2.5.2.1 Chaining a NAM Block to a FAB - Specify the NAM block 
associated with a FAB by placing its address in the 1-word NAM field 
of the FAB. 



2.5.2.2 Chaining XABs to a FAB - Specify the XABs associated with a 

FAB by placing the address of the first XAB in the 1-word XAB field of 

the FAB; in each XAB, specify the address of the next XAB in the 

chain in the 1-word NXT field of the XAB; in the last XAB in the 
chain, specify in the NXT field. 

Follow these rules in ordering XABs in a chain: 

• Place ALL blocks together in the chain. Each ALL block is 
"numbered" by the value in the 1-byte AID field of the ALL 
block; chain ALL blocks so that these numbers are in 
ascending order. For the CREATE operation, begin with and 
do not skip numbers in the ascending sequence; for other 
operations, you can skip numbers in the sequence. 
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• Place no more than one DAT block in the chain. 

• Place KEY blocks together in the chain. Each KEY block is 
"numbered" by the value in the 1-byte REF field of the KEY 
block; chain KEY blocks so that these numbers are in 
ascending order. For the CREATE operation, begin with and 
do not skip numbers in the ascending sequence; for other 
operations, you can skip numbers in the sequence. 

• Place no more than one PRO block in the chain. 

• Place no more than one SUM block in the chain. 



2.5.2.3 Chaining a FAB to a RAB 

operation creates a stream for a 
RAB specifies the stream. Specify 
in the 1-word FAB field of the RAB 



(CONNECT Operation) - The CONNECT 
file. A FAB specifies the file; a 
the address of the FAB for the file 
for the stream. 



2.5.3 Calling Operation Routines 

Use RMS -11 operation macros to call operation routines. You can 
specify arguments for the operation routine either by giving them as 
arguments to the operation macro, or by placing them in an argument 
block in memory. 



2.5.3.1 Call with Macro Arguments - Call an operation routine (except 
RENAME) using an operation macro with arguments in the format: 

$macroname blkaddr [ , [er raddr ] [,sucaddr]] 

where $macroname is the name of an operation macro (except $RENAME) ; 

blkaddr is the address of a FAB (for a directory or file operation) or 

a RAB (for a stream, record, or block operation); erraddr is the 

address of an error handler for the operation; and sucaddr is the 
address of a success handler for the operation. 

For example, if you want to open a file using a FAB at address INFAB 
and want to use a success handler at address SUCCES, the macro call 
would be: 

$OPEN #INFAB, ,#SUCCES 

Call the RENAME operation using the $RENAME operation macro with 
arguments in the format: 

$RENAME oldfabaddr, [erraddr] , [sucaddr] ,newfabaddr 

where oldfabaddr is the address of a FAB for the old file 
specification; erraddr is the address of an error handler for the 
operation; sucaddr is the address of a success handler for the 
operation; and newfabaddr is the address of a FAB for the new file 
specification . 
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2.5.3.2 Call with Arguments in Memory - To call an operation routine 
using an operation macro with arguments in an argument block in 
memory, omit the arguments to the macro, store the address of the 
argument block in register R5, and store the argument block in memory 
as follows: 



ARGUMENT COUNT 



ADDRESS OF FAB OR RAB 2 



ADDRESS OF ERROR HANDLER (OPTIONAL) 4 



ADDRESS OF SUCCESS HANDLER (OPTIONAL) 6 



ADDRESS OF NEW FAB (RENAME ONLY) 10 



ZK-1097-82 



The argument count is 4 for a RENAME operation; otherwise it is one 
of the following: 

• 1 - no completion handlers 

• 2 - error handler, but no success handler 

• 3 - success handler 

If the operation has no error handler, but either has a success 
handler or the operation is RENAME, specify -1 as the address of the 
error handler; if the operation has no success handler, but the 
operation is RENAME, specify -1 as the address of the success handler. 



2.5.4 Handling Returns 

An RMS-11 file or directory operation returns a completion status code 
in the 1-word STS field of the FAB and, for some completions, a 
completion status value in the 1-word STV field of the FAB. 

An RMS-11 stream, record, or block operation returns a completion 
status code in the 1-word STS field of the RAB and, for some 
completions, a completion status value in the 1-word STV field of the 
RAB. 

Appendix A lists completion codes. 

Your program should examine the STS field contents to determine 
whether the operation was successful; even if the operation returned 
an error completion, your program may be able to handle the error and 
recover . 

The program can handle the return (based on the completion code) 
either in the code that immediately follows the operation macro, or in 
special routines (called completion handlers) that the operation can 
call. Section 2.6 shows how to write completion handlers. 
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There are two kinds of fatal RMS-11 errors: 

• If the FAB or RAB address you specify is not the address of a 
valid and idle FAB or RAB, or if the argument block you 
provide is invalid, RMS-11 cannot return values, even in the 
STS field. RMS-11 issues a BPT instruction, leaving status 
information in the following registers: 

RO: RMS-11 fatal error code 

Rl: Stack pointer (at time of entry to RMS-11 routine) 

R2: Program counter (entry return same as @R1) 

R3 : Address of system impure area 

• If RMS-11 detects the corruption of memory-resident data 
structures, or if it detects inconsistent internal states, it 
cannot proceed with its operations. In these cases, RMS-11 
halts execution with a BPT instruction; if it can identify 
the error, RMS-11 leaves an error completion in RO . 

Appendix A lists the symbols and values for RMS-11 fatal error codes. 



2.5.5 Examining Returned Values 

When an RMS-11 operation routine completes its execution, it has 
placed values in control block fields that show the results of the 
operation. Your program should examine these values to determine the 
results. The description of each operation macro in Chapter 6 
discusses the control block fields that return values for that 
operation . 

Three RMS-11 field-access macros help you examine values in control 
block fields: 

• $FETCH copies a value from a field to a specified location. 

• $COMPARE compares a field value to a specified value. 

• $TESTB ITS determines whether specified bits in a field are 
set . 



2.5.5.1 l?FETCH Macro - Use the $FETCH macro to copy a value from a 
control block field to a specified location. The format for the 
$FETCH macro is : 

$FETCH dst,fld,reg 

where dst is an address in memory; fid is the mnemonic for a control 
block field; and reg is a general purpose register (RO through R5) 
containing the address of the control block. 

The $FETCH macro looks up the size of the source field, so that it can 
copy the correct number of bytes or words. If the destination is a 
register and the source is a 1-byte field, then the byte is copied to 
the low byte of the register and the high byte is cleared. if the 
destination is a register and the source is a multiword field, then 
the multiword field is copied to the specified register and following 
registers . 
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The $FETCH macro generates an error during assembly if you use an 
illegal address mode for the destination. For multiword fields, 
illegal address modes are autoincrement deferred, autodecrement 
deferred, and indexed deferred. Immediate mode is illegal for $FETCH, 
regardless of field size. 

It is also illegal to use the program counter (PC) as the destination 
or to specify a register for the destination in such a way that the 
destination overlaps the register that contains the control block 
address . 

At execution time, the $FETCH macro copies the contents of the control 
block field to the specified location. The number of bytes or words 
copied is the same as the field size for the mnemonic. Chapter 6 
gives the size of each control block field. 

As an example of the use of the $FETCH macro, suppose that you want to 
fetch the allocation quantity ( ALQ field) from a FAB to a location 
labeled ALQSAV, and suppose also that the address of the FAB is in 
register R3. Then the proper macro is: 

$FETCH ALQSAV, ALQ, R3 ;Save allocation quantity 

and two words are copied from the ALQ field to memory beginning at 
ALQSAV. 



2.5.5.2 $COMPARE Macro - Use the $COMPARE macro to compare the 
contents of a 1-byte or 1-word control block field with a specified 
value. The format for the $COMPARE macro is: 

$COMPARE src,fld,reg 

where src is an address in memory; fid is the mnemonic for a control 
block field; and reg is a general purpose register (RO through R5) 
containing the address of the control block. 

If the given field is not a 1-byte or 1-word field, the $COMPARE macro 
generates an error during assembly. 

At execution time, the $COMPARE macro executes a machine instruction 
that compares the source value and the field contents. The 
instruction executed depends on the size of the specified field and on 
the specified source: 

• TSTB for a 1-byte field and the source #0 

• TST for a 1-word field and the source #0 

• CMPB for a 1-byte field and a source other than #0 

• CMP for a 1-word field and a source other than #0 
Chapter 6 gives the size of each control block field. 

For example, suppose that you want to compare the value in the RSZ 
field of a RAB with a value stored in a location labeled RSZSAV, and 
suppose also that the address of the RAB is stored in register R2. 
Then the proper macro is: 

$COMPARE RSZSAV, RSZ ,R2 ;Compare record size 
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Suppose that you want to compare the same RSZ field to the value of a 
symbol, RECSIZ. Then the proper macro is: 

$COMPARE #RECSIZ , RSZ , R2 ;Compare record size 



2.5.5.3 $TESTBITS Macro - Use the $TESTB ITS macro to test the values 
of bits in a 1-byte or 1-word control block field. Chapter 6 gives 
the size of each control block field. The format for the $TESTBITS 
macro is: 

$TESTBITS mask, fid, reg 

where mask is an address in memory containing bits to be tested; fid 
is the mnemonic for a control block field; and reg is a general 
purpose register (RO through R5) containing the address of the control 
block . 

If the given field is not a 1-byte or 1-word field, the $TESTBITS 
macro generates an error during assembly. 

At execution time, the $TESTBITS macro executes a machine instruction 
that tests the bits specified in the mask. The instruction executed 
depends on the size of the specified field: 

• BITB for a 1-byte field 

• BIT for a 1-word field 

For example, suppose you want to determine whether the terminal device 
is set in the DEV field of a FAB, and suppose that the address of the 
FAB is in register R3 Then the proper macro is: 

$TESTBITS #FB$TRM , DEV, R3 ;Terminal device? 

As another example, suppose that you want to determine whether either 
the contiguous-area or the hard-location bit is set in the AOP field 
of an ALL block, and suppose that the address of the ALL block is in 
register R2. Then the proper macro is: 

$TESTBITS #XB$CTG!XB$HRD,A0P,R2 ;Contiguous or hard location? 



2.6 WRITING COMPLETION HANDLERS 

Recall that when you use an RMS-11 operation macro, you can specify 
the addresses of completion handlers for the operation; if you do so, 
the operation automatically calls the error handler (for a nonfatal 
error completion) or the success handler (for a success completion) 
when the operation completes, before control returns to your program. 

When execution control passes to your completion handler, it finds the 
following situation: 

• Register R5 contains the address of the argument block for the 
operation . 

If the operation is asynchronous, the address is the address 

of a copy of the original argument block for the operation. 

• The second word of the argument block contains the address of 
the FAB or RAB for the operation. (Recall that the STS and 
STV fields of the FAB or RAB contain the completion code and 
completion value for the operation.) 
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• If the operation was RENAME, the fifth word of the argument 
block contains the address of a second FAB for the operation. 

• Other blocks are chained as they were when you used the 
operation macro that called the operation routine. 

A completion handler cannot determine from these values which RMS-11 
operation was executed, or what part of your program called the 
operation routine. You can, however, use the 1-word CTX field of the 
FAB or the 1-word CTX field of the RAB to indicate the context of the 
operation; RMS-11 does not disturb values in CTX fields. 

The completion handler must preserve the stack pointer (SP) , and must 
end with the RMS-11 completion-return macro in the format: 

$RETURN ;End of completion handler 



2.7 USING GET-SPACE ROUTINES 

Your program can provide and use get-space routines other than the one 
provided with RMS-11. It can set an initial get-space routine at 
assembly time, and it can change to other routines during program 
execution. Section 2.7.1 shows how to specify get-space routines, and 
how to obtain the address of the current get-space routine. Section 
2.7.2 shows how to write a get-space routine. 



2.7.1 Specifying Get-Space Routines 

To specify a get-space routine at assembly time, use the GSA$ macro in 
the format: 

GSA$ address ;Initialize get-space routine 

; address 

where address is the get-space routine entry address. If you specify 
as the address, or if you do not use the GSA$ macro, the initial 
get-space routine for the program is the RMS-11 routine. 

For example, to specify a routine that begins at the label MYSPAC, you 
would use: 

GSA$ MYSPAC 

To change the get-space routine during program execution, use the 
$SETGSA macro in the format: 

$SETGSA pointer ;Change get-space routine 

where pointer is the address of a location that contains the get-space 
routine entry address. If you specify the entry-point address as 0, 
the new get-space routine established is the RMS-11 routine. 

For example, to specify a routine that begins at the label NEWSPC, you 
could use: 

$SETGSA #NEWSPC 

Alternatively, if the location GSATMP contains the value NEWSPC, you 
could use: 

$SETGSA GSATMP 
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To obtain the address (in RO) of the current get-space routine during 
program execution, use the $GETGSA macro in the format: 

$GETGSA ;Get-space routine address into RO 

If the address returned in RO is 0, the current get-space routine is 
the RMS-11 routine. 



2.7.2 Writing a Get-Space Routine 

A get-space routine handles space in contiguous blocks. For a request 
for space, it allocates a contiguous block of space (or denies the 
request); for a release of space, it accepts a contiguous block of 
space . 

A get-space routine must have a proper interface to calling routines, 
and it should handle unallocated space properly. 



2.7.2.1 Get-Space Routine Interface - When RMS-11 calls a get-space 
routine, it either requests or releases a block of space. For a 
request for space, registers RO through R2 contain the following 
values : 

RO Address of pool free-space list (see next section) 
Rl Size (in bytes) of requested block 
R2 

If the get-space routine fills the request, it must clear the C bit 
and return the address of the first word of the allocated block in RO ; 
if it does not fill the request, it must set the C bit. In either 
case, the routine must preserve the stack and registers R3 through R6 . 

For a release of a block of space, registers RO through R2 contain the 
following values: 

RO Address of pool free-space list (see next section) 
Rl Size (in bytes) of released block 
R2 Address of first word being released 

For a release-space operation, the get-space routine returns no 
values; however, it must preserve the stack and registers R3 through 
R6. 



2.7.2.2 Pool Free-Space Lists - When RMS-11 calls your get-space 
routine, the address of a pool free-space list is in register RO . 
This free-space list specifies free space in one of the five pools 
described in Section 2.3; you can use this pool (which may or may not 
have adequate free space) , or you can use a pool of your own. 

The free-space list chains free contiguous blocks of the pool. The 
first word of each block contains the address of the next block; if 
the first word of a block is 0, it is the last block in the list. 

Blocks in the list are ordered by ascending virtual addresses; their 
addresses are word-aligned; their sizes are multiples of 4 bytes 
(allocations and deallocations must be rounded up to a multiple of 4, 
if necessary) . 
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The second word of each block contains the size (in bytes) of the 
block, including the 4-byte header; the first "block" in the list 
contains in its second word, since it is the header block for the 
list . 

Your get-space routine can use the specified pool list to get space 
for RMS-11; if it does this, it must properly maintain the list, and 
must (if possible) merge blocks back into the pool. 

The system routines $RQCB and $RLCB are suitable for handling pool 
free-space lists. These routines have interfaces that meet the 
requirements for your get-space routine; therefore your program can 
jump to $RQCB (for a space request) or $RLCB (for a space release) . 



2.8 ASSEMBLING THE PROGRAM 

When you assemble your program, you must cause the assembler to get 
RMS-11 macro and symbol definitions from a library, and you may have 
to correct errors indicated by messages from RMS-11 macros. 



2.8.1 Assembling with the RMSMAC Macro Library 

When you assemble your program, the assembler needs definitions for 
the RMS-11 macros and symbols that your program uses; these are in 
the RMS-11 macro library, RMSMAC . MLB . Include the following reference 
to the RMS-11 macro library in your assembler command string: 

LB : [1,1] RMSMAC . MLB/ML 



2.8.2 Assembly-Time Errors from RMS-11 Macros 

RMS-11 macros detect some errors during assembly. For each such 
error, a macro issues a .PRINT or .ERROR assembler directive with a 
message. Appendix B describes RMS-11 macro-generated messages and 
their meanings. 
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CHAPTER 3 
PROCESSING DIRECTORIES AND FILES 



This chapter discusses use of RMS-11 directory and file operations. 
The next sections discuss information and usage common to several 
directory and file operations: 

• Device characteristics 

• Logical channels 

• File specifications and identifiers 

• Private buffer pools 

• Completion status 

The sections after those provide an overview of the operations 
themselves (see Chapter 5 for detailed discussions): 

• Directory operations (except SEARCH) : ENTER , REMOVE, RENAME 
and PARSE 

• File operations: CREATE, OPEN, DISPLAY, ERASE, EXTEND, and 
CLOSE 

Finally, the last sections discuss: 

• SEARCH operation 

• Writing wildcard loops 



3.1 DEVICE CHARACTERISTICS 

A directory or file operation (except CLOSE, DISPLAY, or EXTEND) 
returns device characteristics. These characteristics are returned as 
masks in the 1-byte DEV field of the FAB. The device characteristics 
are : 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 
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• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



3.2 LOGICAL CHANNELS 

An RMS-11 directory or file operation (except CLOSE, DISPLAY, or 
EXTEND) requires a logical channel; this channel is a path from the 
program to a specified device. 

When your program executes a CREATE or OPEN operation on the channel, 
the path is extended to the target file; until the file is closed, 
the channel is reserved for the specified FAB. 

Your program specifies the logical channel for a directory operation 
or for a CREATE, ERASE, or OPEN operation in the 1-byte LCH field of 
the FAB; the channel must not already be in use by the task. 

You can specify the initial device assignment for a logical channel in 
a Task Builder command file. The Task Builder also provides default 
initial device assignments for certain channels. Other logical 
channels are unassigned when your task begins executing. 

During task execution, channel assignments are made or changed by use 
of the ALUN$ system directive. For example, RMS-11 uses the ALUN$ 
directive to assign a logical channel for a directory operation or for 
a CREATE, ERASE, or OPEN operation; if the FAB and NAM block specify 
a device or device identifier, RMS-11 assigns the channel to that 
device; if the FAB and NAM block do not specify a device or device 
identifier, RMS-11 retains the device-channel assignment (if any), or 
assigns the channel to the device SY:. 



3.3 FILE SPECIFICATIONS AND IDENTIFIERS 

A file specification consists of the following elements (in the order 
g i ven) : 

• Device specification - the device where the file resides 

• Directory specification - the directory on the device through 
which the file can be found 

• File name - the name by which the file is known in the 
directory 

• File type - the type by which the file is known in the 
d i rectory 

• File version - the version number by which the file is known 
in the directory 
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RMS-11 operations construct and use file specification strings and 
file identifiers to specify files. These strings and identifiers 
include : 

• User-provided file specification strings 

• Expanded file specification strings 

• Resultant file specification strings 

• File, directory, and device identifiers 

This section discusses these strings and identifiers as they are used 
for nonwildcard operations; wildcard use is described in Section 3.8. 

For a CREATE , ENTER, ERASE, OPEN, PARSE, REMOVE, or RENAME operation, 
your program specifies two strings to be used in generating a full 
file specification: 

• A file specification string, called the file string (your 
program specifies the address of the file string in the 1-word 
FNA field of the FAB and the length of the string in the 
1-byte FNS field of the FAB) 

• A default file specification string, called the default string 
(your program specifies the address of the default string in 
the 1-word DNA field of the FAB and the length of the string 
in the 1-byte DNS field of the FAB) 

The operation routine uses these two strings to form an internal 
merged file specification string, called the merged string. The 
operation initially forms the merged string as follows: 

• It begins by taking available elements from the file string. 

• It then supplies missing elements from the default string (if 
they are available there) . The operation (when it completes) 
returns masks describing the results of this merge in the 
1-word FNB field of the NAM block (if you supplied a NAM block 
for the operation) . 

If elements are still missing from the merged string, the operation 
next adds the following elements: 

• Device - If the logical channel specified in the LCH field of 
the FAB is already assigned to a device, that device is used; 
otherwise the device SY: is used. 



• Directory - The task's current directory is used. 

• File name, type, and version - Nulls are used. 

If the operation is the PARSE operation, the merged string is 
complete. If you provided a NAM block, the PARSE operation returns 
the device identifier in the 2-word DVI field of the NAM block; if 
you provided an expanded string buffer, the PARSE operation returns 
the expanded string in the expanded string buffer (whose address is in 
the 1-word ESA field of the NAM block) . (Note that the device 
specification in an expanded string has usually been translated to the 
specification for a physical device.) 
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An operation other than PARSE continues by examining the FB$F ID mask 
in the FOP field of the FAB. If the FB$FID mask is set, the operation 
adds the following elements: 

• Device - If a device identifier is given in the NAM block, 
that device overrides the device in the merged string and the 
device specification is deleted from the merged string. 

• Directory - If a directory identifier is given in the NAM 
block, that directory overrides the directory in the merged 
string and the directory specification is deleted from the 
merged string. 

• File identifier - If a file identifier is given in the NAM 
block and if the operation is ERASE or OPEN, that file 
overrides the directory, file name, type, and version in the 
merged string and the specifications for those elements are 
deleted from the merged string. 

The merged string is then copied to the expanded string buffer (if you 
supplied one) as described for the PARSE operation above. The merged 
string plus applicable identifiers are called the fully qualified file 
specification, and define the file upon which the operation will be 
performed . 

The device, directory, and file identifiers for the file are returned 
in the NAM block (if you supplied one). These identifiers can be used 
as input to subsequent directory and file operations to speed 
processing by eliminating directory and file lookups. 

Note that a complete file specification is relevant only to a disk 
file. The directory specification is not relevant for ANSI magtape 
files; only the device specification is relevant for a file on a 
unit-record device. Irrelevant elements are not processed, and appear 
in the expanded string only if your program provides them in the file 
string or default string. 



NOTE: NULL, 0, OR -1 VERSION NUMBER 

If the version specification has not 
been deleted and is null, 0, or -1, it 
will later be replaced with the version 
number of the target file. 

A version number of -1 identifies the 
target file as the (otherwise) specified 
file with the lowest version number; a 
version number of -1 is illegal for a 
CREATE or ENTER operation, or for the 
new file specification for a RENAME 
operation . 

For an ERASE, OPEN, REMOVE, or RENAME 
(old specification) operation, a null or 
version number specifies the target 
file as the (otherwise) specified file 
with the highest version number. 

For a CREATE, ENTER, or RENAME (new 

specification) operation, a null or 

version number specifies that the 
operation is to create a new entry whose 

version number is one greater than the 

highest-numbered version of the 
(otherwise) specified file. 
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3.4 PRIVATE BUFFER POOLS 

Many RMS-11 operations require space from a buffer pool. A directory 
or file operation (except CLOSE, DISPLAY, or EXTEND) allows your 
program to specify a private buffer pool. Your program specifies the 
address of the pool in the 1-word BPA field of the FAB; it specifies 
the size (in bytes) of the pool in the 1-word BPS field of the FAB. 

The CLOSE operation returns (in the BPA and BPS fields) the address 
and size of the private buffer pool (if any) specified for the CREATE 
or OPEN operation that opened the file; until the file is closed, the 
pool is dedicated to the open file and must not be used for other 
purposes . 

If your program does not specify a private buffer pool, the operation 
uses the central buffer pool (which your program declares using 
pool-declaration macros) ; if your program specifies a private buffer 
pool, the operation uses that pool. 

The CLOSE, DISPLAY, and EXTEND operations, and all stream, record, and 
block operations use the pool specified by the CREATE or OPEN 
operation that opened the file. 



3.5 COMPLETION STATUS 

A directory or file operation returns a completion status code in the 
1-word STS field of the FAB, and a completion status value in the 
1-word STV field of the FAB. 



3.6 DIRECTORY OPERATIONS 

RMS-11 directory operations affect only directory entries (not the 
contents of files). The directory operations are: 

• ENTER: create a directory entry 

• REMOVE: delete a directory entry 

• RENAME: replace a directory entry 

• PARSE: analyze a file specification 

• SEARCH: search directories 

The next sections provide an overview of the directory operations 
(except for the SEARCH operation, which is discussed in Section 3.8). 



3.6.1 ENTER Operation 

A file specified as temporary when it was created has no directory 

entry; a file also has no directory entry if the entry has been 
deleted by the REMOVE operation. 

Your program can use the ENTER operation to create a directory entry 

for a file; this makes it possible for your program (and other 

programs) to specify the file to RMS-11 by its file specification. 

The ENTER operation uses the device and directory elements of the 
fully qualified file specification to determine the target directory; 
it then creates an entry in that directory using the file name, type, 
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and version elements of the fully qualified file speci f icat ion , and 
the file identifier specified in the NAM block. 



3.6.2 REMOVE Operation 

Your program can delete the directory entry for a file by using the 
REMOVE operation; this does not affect either the existence of the 
file or the file contents, but only removes the path to the file. 

The device and directory elements of the fully qualified file 
specification specify the target directory; the file name, type, and 
version elements of the fully qualified file specification identify 
the entry to be removed from the directory. 



3.6.3 RENAME Operation 

Your program can replace the directory entry for a file by using the 
RENAME operation. The fully qualified file specification for the new 

directory entry must not specify a new device for the file, but 

otherwise it can specify elements different from the old file 
specification: directory, file name, file extension, and file version 
number . 

If you do not specify a device, the device associated with the old 
file specification is used. 

For both the old and new directory entries, the RENAME operation uses 

the device and directory elements of the fully qualified file 

specification to determine the target directory; it uses the file 

name, type, and version elements of the fully qualified file 
specification to identify the entry to be removed or created. 



3.6.4 PARSE Operation 



Your program can use the 
specification, or to prepare 
(described in Section 3.8). The 
described in detail in Section 3 



PARSE operation 
for a series 
results of the 
3. 



to analyze a file 
of wildcard operations 
PARSE operation are 



3.7 FILE OPERATIONS 

RMS-11 file operations affect files as whole entities (but not 
individual records or blocks in files). The file operations are: 

• CREATE: create a file (and a corresponding directory entry) 
and open the file for processing 

• OPEN: open an existing file for processing 

• DISPLAY: write file information to control blocks 

• ERASE: delete file contents (records or blocks) and remove 
directory entry 
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• EXTEND: increase the allocation for a file 

• CLOSE: close an open file 

The next sections discuss file operations. 



3.7.1 CREATE Operation 

The CREATE operation creates a new file and opens it for processing; 
unless the file is specified as a temporary file, the CREATE operation 
also creates a directory entry for the file. 

The CREATE operation uses the device and directory elements of the 
fully qualified file specification to determine the target directory; 
it then uses the file name, type, and version of the fully qualified 
file specification to form the entry in that directory. 



3.7.2 OPEN Operation 

Your program can establish an access path to a file by using the OPEN 
operation. This makes file information available to your program, and 
enables your program to use the following operations for the file: 

• DISPLAY operation (to make more file information available to 
your program) . 

• EXTEND operation (to allocate more space for the file) . 

• CONNECT operation (to establish a path to file records or 
blocks) . The CONNECT operation enables your program to use 
other stream operations and either record operations or block 
operations . 

• CLOSE operation (to release resources committed to the open 
file). The CLOSE operation terminates the access path 
established by the CREATE or OPEN operation that opened the 
file. 



3.7.3 DISPLAY Operation 

If your program uses the OPEN operation to open a file, but does not 
provide control blocks and buffers for all the information that the 
OPEN operation can return, you may want to use the DISPLAY operation 
to obtain additional information while the file is open. 



3.7.4 ERASE Operation 

Your program can erase the contents of a file by using the ERASE 
operation, and (optionally) remove its directory entry. 

Unless your program provides a file identifier in the NAM block and 
sets the FB$FID mask in the 1-word FOP field of the FAB, the ERASE 
operation also removes the specified directory entry for the file. 
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The ERASE operation uses the fully qualified file specification to 
determine the target file. If the operation removes the directory 
entry, it uses the device and directory elements of the fully 
qualified file specification to determine the target directory, and 
the file name, type, and version elements to determine the entry to be 
removed . 



3.7.5 EXTEND Operation 

Your program can increase the allocation for an open file by using the 
EXTEND operation. Note that RMS-11 automatically extends the file 
allocation when it needs more space; you can use the EXTEND operation 
to make large extensions (avoiding repeated automatic extensions) or 
exact extensions (avoiding wasteful automatic extensions). 



3.7.6 CLOSE Operation 

Your program can close an open file by using the CLOSE operation. 
This releases task and system resources (other than the file itself) 
and makes those resources available for other uses. 



3.8 WRITING WILDCARD LOOPS 

You can include wildcard characters in an RMS-11 file specification 
and use the PARSE and SEARCH operations to identify files that match 
the wildcard specification. This allows you to program a wildcard 
loop that successively (and selectively, if you wish) processes files 
matching the wildcard specification. 

An advantage of RMS-11 wildcarding over system wildcard commands is 
that your processing can be selective. For example, if you use a 
system wildcard command to rename a group of files, the entire group 
is renamed; if you use a wildcard loop in a program, the program can 
fully examine information about each file and even the contents of 
each file to decide whether to rename it. 

The next three sections show: 

• The structure of a wildcard loop and the behavior of directory 
and file operations in the loop 

• How to write a wildcard loop that nonselect i vely uses the 
ERASE, REMOVE, or RENAME operation on successive matching 
files 



• How to write a wildcard loop that selectively performs 
directory and file operations on successive matching files 



3.8.1 Introduction to Wildcarding 

This discussion assumes that you want to write a program loop that 
uses a wildcard input file specification, and that you want to use the 
same control blocks (FAB and NAM block) for all operations associated 
with the wildcard loop. 
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A series of wildcard operations can be viewed as having four steps: 

1. Initializing for wildcarding 

2. Finding the next matching file 

3. Operating on the found file 

4. Ending wildcarding 

The next sections discuss these steps. 



3.8.1.1 Initializing for Wildcarding - The PARSE operation 
initializes control blocks (FAB and NAM block) for wildcard 
operations. Place the $PARSE macro before the wildcard loop in your 
program . 

The PARSE operation sets the NB$WCH mask in the 1-word FNB field of 
the NAM block to show that wildcard operations are in progress. (Your 
program must clear the NB$WCH mask if it will not perform SEARCH 
operations after a PARSE operation.) 

The PARSE operation also forms a match-pattern in the expanded string 
buffer (whose address is in the 1-word ESA field of the NAM block) ; 
this match-pattern is used by subsequent wildcard SEARCH operations. 

A series of SEARCH operations requires a NAM block that specifies both 
expanded string and resultant string buffers. (The resultant string 
buffer is specified in the 1-word RSA field of the NAM block.) Your 
program must not alter the expanded string, the resultant string, or 
other NAM block contents between the PARSE operation and the end of 
the subsequent series of SEARCH operations. 



3.8.1.2 Finding the Next Matching File - The SEARCH operation finds 
the next file (if any) that matches the wildcard input file 
specification. (If the SEARCH operation cannot find another matching 
file, wildcarding ends; see Section 3.8.1.4.) 

The SEARCH operation returns a fully qualified file specification in 
the resultant string buffer, along with device, directory, and file 
identifiers for the found file. 

The SEARCH operation in your wildcard loop can either be explicit 
(your loop contains the $SEARCH macro) or, for some operations, 
implicit (RMS-11 automatically performs the SEARCH operation) . If you 
use the explicit SEARCH operation, place the $SEARCH macro inside the 
loop but before other operation macros. 

If you use an ERASE, REMOVE, or RENAME (old FAB) operation in the loop 
with the FB$FID mask in the 1-word FOP field of the FAB cleared, 
RMS-11 implicitly performs a SEARCH operation (to find the next 
matching file) before performing the ERASE, REMOVE, or RENAME 
operation. This allows your wildcard loop to omit the $SEARCH macro. 
(If the implicit SEARCH operation cannot find another matching file, 
wildcarding ends; see Section 3.8.1.4.) 
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3.8.1.3 Operating on the Found File - A number of directory and file 
operations are wildcard-transparent in the sense that they preserve 
both wildcard context information and information about the last-found 
file. This means that your program can use the operations within a 
wildcard loop without changing the wildcard context; the series of 
wildcard operations is continuable. 

The wildcard-transparent operations are CLOSE, DISPLAY, and EXTEND, 
and (if the FB$FID mask in the 1-word FOP field of the FAB is set) 
ERASE, OPEN, REMOVE, and RENAME (old FAB) . 



3.8.1.4 Ending Wildcarding - A series of wildcard operations (using a 
specific FAB and NAM block) ends when a directory or file operation 
discards wildcard context information or when your program clears the 
NB$WCH mask in the 1-word FNB field of the NAM block. 

Typically, the operation that ends wildcarding is a SEARCH operation 
that cannot find another matching file. It returns the ER$NMF 
completion status code and clears the NB$WCH mask in the 1-word FNB 
field of the NAM block. 

If your program exits from a wildcard loop before the SEARCH operation 
fails to find a matching file, the NB$WCH mask in the 1-word FNB field 
of the NAM block is still set, and your program must clear it. 

Executing the PARSE operation during a wildcard series ends that 
series and initializes control blocks for a new series. 

Executing a CREATE or ENTER operation, or an OPEN operation with the 
FB$F ID mask in the 1-word FOP field of the FAB cleared, ends the 
wildcard series for that FAB. 



3.8.2 Nonselective ERASE, REMOVE, or RENAME Wildcard Operations 



You can write a wildcard loop that performs nonselective ERASE, 
REMOVE, or RENAME operations on successive matching files, where 
RMS-11 implicitly performs a SEARCH operation before each ERASE, 
REMOVE, or RENAME operation. 

To do this, do the following: 

1. Use the PARSE operation to initialize control block fields 
for wildcarding. 

2. Clear the FB$F ID mask in the 1-word FOP field of the FAB (for 
the RENAME operation, the old FAB) . This causes the ERASE, 
REMOVE, or RENAME operation to perform an implicit SEARCH 
operation before performing its own processing. 

3. Use the ERASE, REMOVE, or RENAME operation to operate on the 
next matching file. 

4. Examine the STS field of the FAB. If it contains the ER$NMF 
completion status code, there was not another matching file; 
in that case, go to step 7. 

5. Perform other in-loop processing (such as reporting the file 
specification of the erased, removed, or renamed file). 
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6. Go to step 2. 

7. The wildcard 
processing . 



series is finished; continue with other 



The following program segment illustrates this procedure, performing 
the ERASE operation. In the program segment, FABADR is a label giving 
the address of the FAB for the operations, and RO is used (for the 
$STORE and $COMPARE macros) to contain the address of the FAB. 



LOOP: 



$PARSE 


#FABADR 


;Set up for wildcarding 


MOV 


#FABADR,R0 


; FAB address to RO 


$OFF 


#FB$FID,FOP, RO 


;Use implicit search 






; (FB$FID off) 


$ERASE 


#FABADR 


;Try to erase next file 


$COMPARE 


#ER$NMF,STS, RO 


;Was there a matching file? 


BEQ 


DONE 


;No more matching files 






;Other in-loop processing 


BR 


LOOP 


;On to next matching file 



DONE 



;Continue with other 
; processing 



3.8.3 Selective Wildcard Operations 

You can write a wildcard loop that performs directory and file 
operations on selected matching files, where your program explicitly 
performs a SEARCH operation at the beginning of each iteration of the 
loop. To do this, do the following: 

1. Use the PARSE operation to initialize control block fields 
for wildcarding. 

2. Use the SEARCH operation to obtain information about the next 
file that matches the wildcard specification. 

3. Examine the STS field of the FAB. If it contains the ER$NMF 
completion status code, there was not another matching file; 
in that case, go to step 6. 

4. Perform directory and file operations on the found file. If 
ERASE, OPEN, REMOVE, or RENAME operations are included, be 
sure the FB$F ID mask in the 1-word FOP field of the FAB (for 
the RENAME operation, the old FAB) is set. 

Do not perform CREATE, ENTER, or PARSE operations, or OPEN 
operations with the FB$F ID mask cleared; these operations 
end wildcarding. 

Do not perform ERASE, REMOVE, or RENAME operations with the 
FB$FID mask cleared; these operations perform an implicit 
SEARCH operation, advancing to the next matching file. 

5. Go to step 2. 

6. The wildcard series is finished; continue with other 
process i ng . 



3-11 



PROCESSING DIRECTORIES AND FILES 



The following program segment illustrates the procedure, performing 
the ERASE operation on selected files. In the program segment, FABADR 
is a label giving the address of the FAB for the operations, and RO is 
used (for the $COMPARE macro) to contain the address of the FAB. 



$PARSE 



#FABADR 



;Set up for wildcarding 



LOOP: 



$SEARCH 
MOV 

$COMPARE 
BEQ 



#FABADR 
#FABADR , RO 
#ER$NMF,STS,RO 
DONE 



Find next matching file 
FAB address to RO 
Any more matching files? 
No more matching files 
Decide whether to delete 



NOOP: 



BNE 
MOV 
$SET 



BR 



$ERASE 



NOOP 

#FABADR , RO 

#FB$FID,FOP,R0 

#FABADR 



LOOP 



file (if so, Z-bit on) 
Don't delete file 
FAB address to RO 
Explicit SEARCH already done 
Erase file contents 
Other in-loop processing 
On to next matching file 



DONE: 



;Continue with other 
; processing 
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PROCESSING RECORDS AND BLOCKS 



This chapter describes use of RMS-11 stream, record, and block 
operations; its major sections are: 

• Synchronous and asynchronous operations 

• Completion status 

• Streams 

• Record processing 

• Block processing 



4.1 SYNCHRONOUS AND ASYNCHRONOUS OPERATIONS 

An RMS-11 stream, record, or block operation executes either 
synchronously or asynchronously. 



4.1.1 Synchronous Operations 

If an operation executes synchronously, execution control is not 
returned to your program until the operation has completed; your 
program is idle during the operation's execution. To specify 
synchronous operation for a stream, record, or block operation, clear 
the RB$ASY mask in the 1-word ROP field of the RAB. 



4.1.2 Asynchronous Operations 

If an operation executes asynchronously, execution control may be 
returned to your program before the operation has completed; this 
allows your program to continue executing during the operation's 
execution. To specify asynchronous operation for a stream, record, or 
block operation, set the RB$ASY mask in the 1-word ROP field of the 
RAB. (You must also have specified the ASYN argument to the RAB$B 
macro when you declared the RAB, and must select the asynchronous 
support modules when you task build your program.) 

Your program can, for example, specify an asynchronous write operation 
and continue its processing even while the file processor is waiting 
for access to the device. 
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Only one operation (either synchronous or asynchronous) at a time may 
be active for a stream. Your program must make sure that an 
asynchronous operation has completed either by using the WAIT 
operation or by using completion routines to set user-defined flags. 

During processing, RMS-11 guards against illegal interleaving of 
operations on the same file as follows: 

• A file operation begins by verifying that no record operation 
is in progress for the target file. 

• A record operation begins by verifying that no file operation 
is in progress for the target file. 

• If a synchronous operation detects that it is executing within 
an asynchronous operation's completion handler, it verifies 
that no other record operation is in progress for the target 
file. 

If one of these verifications fails, the operation returns the ER$ ACT 
completion in the STS field of the FAB or RAB. 

If your program attempts an operation using a FAB or RAB that is 
already in use by another operation, the attempted operation returns 
the fatal completion ER$ACT in RO (because the STS field of the FAB or 
RAB belongs to the other operation) . 

If your program attemps a WAIT operation within the completion handler 
for an asynchronous operation, the attempted operation returns the 
fatal completion ER$AST in RO (because otherwise a deadlock could 
occur) . 



4.2 COMPLETION STATUS 

A stream, record, or block operation returns a completion status code 
in the 1-word STS field of the RAB; it may also return a completion 
status value in the 1-word STV field of the RAB. 



4 . 3 STREAMS 

A stream is a path from your program to the data in a file. The 
CONNECT operation establishes a stream; for the CREATE or OPEN 
operation that opened the file, your program specified either record 
access or block access. 

If it specified record access, the stream is a record stream and 
supports only stream operations and record operations; if it 
specified block access, the stream is a block stream and supports only 
stream operations and block operations. 

For the CONNECT operation, your program specifies the FAB for the file 
(in the 1-word FAB field of the RAB) , and the CONNECT operation 
returns an internal stream identifier (in the 1-word ISI field of the 
RAB) . All stream, block, and record operations (except CONNECT) 
identify the file using the internal stream identifier; the 
DISCONNECT operation terminates the stream, and clears the internal 
stream identifier. 
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4.4 RECORD PROCESSING 

This section describes use of RMS-11 record processing. Its 
subsections are: 

• Record streams: the paths from your program to file records 

• Record context: the "current location" of a stream in a file 

• Record access modes: the ways your program can access records 

• Record buffers: the locations of records in your program's 
space 

• Locate mode: a way of speeding record processing 

• Stream operations: stream operations for a record stream 

• Record operations: operations that access records 



4.4.1 Record Streams 

A record stream is a path from your program to the records in a file. 
Your program establishes a record stream when it uses the CONNECT 
operation to connect a stream to a file (opened for record access by 
an earlier CREATE or OPEN operation) . A record stream supports stream 
operations and record operations, but not block operations. 

If the target file for a stream is a relative or indexed file, your 
program can establish more than one stream for the file; if, in 
addition, your program specifies access sharing, more than one task 
can establish streams for the file. 



4.4.2 Record Context 

A record stream has a record context, which consists of a 
current-record context and a next-record context. Some record 
operations use the current record or next record as the target for the 
operation; some stream and record operations change the 
current-record context, the next-record context, or both. 

The notion of "following record" is important to record context 
because the next-record context is often established as the record 
"following" the current record. The precise meaning of "following 
record" depends on the file organization: 

• In a sequential file, the record following a given record is 
the one immediately following it in physical sequence. 

• In a relative file, the record following a given record is the 
one in the first higher-numbered cell that contains a record. 

• In an indexed file, a record follows another only with respect 
to an index; each index imposes an order on the file records. 
The record following a given record (under a given index) is 
the record whose record key is the smallest in the file that 
is greater than the record key of the given record; among 
records having identical record keys, a record written later 
follows a record written earlier. 
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Note that although an operation may establish the next-record context, 
that context is not evaluated until another operation uses it. For 
example, if your program connects a stream to a relative file that 
contains records only in cells 5 and 10, a sequential access GET 
operation returns the record in cell 5 and establishes both 
current-record and next-record context; if another stream or task 
then inserts a record in cell 7 before your program executes a second 
sequential access GET operation, that GET operation returns the new 
record (cell 7) , even though the record did not exist when the 
next-record context was established. 



4.4.3 Record Access Modes 

The record operations FIND, GET, and PUT allow your program to specify 
a record access mode (in the 1-byte RAC field of the RAB) ; the record 
access mode determines the target record for the operation. The 
record access modes are: 

• Sequential access 

• Key access 

• RFA access 

The next sections discuss these access modes. 



4.4.3.1 Sequential Access - Your program specifies sequential access 
by setting the RB$SEQ code in the 1-byte RAC field of the RAB. A 
sequential access FIND or GET operation has as its target the next 
record. (Exception: a sequential access GET operation that 
immediately follows any FIND operation has as its target the current 
record, which is the record found by the FIND operation.) 

The target of a sequential access PUT operation depends on the file 
organization, as follows: 

• For a sequential file, a series of sequential access put 
operations must begin with the next-record context at the 
end-of-file. The series of PUT operations adds new records at 
the end-of-file. 

• For a relative file, a series of sequential access PUT 
operations must begin with the next-record context set such 
that the first cell examined is empty (unless the RB$UIF mask 
in the 1-word ROP field of the RAB is set) . The series of PUT 
operations adds new records in successive cells; if a 
nonempty cell is encountered, the PUT operation returns the 
ER$REX completion (unless the RB$UIF mask is set, in which 
case the existing record is overwritten). 

• For an indexed file, a series of sequential access PUT 
operations does not depend on the next-record context; 
however, a PUT operation in the series returns the ER$SEQ 
completion if the value of the record primary key for the 
operation is less than the value of the record primary key for 
the preceding PUT operation. 

A sequential access FIND or GET operation sets the current-record 
context to the target record, and sets the next-record context to the 
record following the target record. Sequential access PUT operations 
leave both the current-record and next-record contexts undefined. 
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This targeting and context setting means, generally speaking, that a 
series of sequential access operations operates on successive records. 
Specifically, series of sequential access operations result as 
f ol lows : 

• A series of sequential access FIND operations sets the stream 
context to successive records. 

• A series of sequential access GET operations reads successive 
records . 

• A series of sequential access PUT operations writes successive 
records (for an indexed file, possibly interspersed with 
existing records) . 

• A series of paired sequential access FIND and sequential 
access GET operations reads successive records. 



4.4.3.2 Key Access - Your program specifies key access by setting the 
RB$KEY code in the 1-byte RAC field of the RAB. A key access FIND, 
GET, or PUT operation has as its target the record that your program 
specifies by specifying the key. For a relative file or for a 
sequential disk file with fixed-length records, your program specifies 
the key as a relative record number. Specify the relative record 
number in the 1-word KBF field of the RAB and the key size as or 4 
in the 1-byte KSZ field of the RAB. 

For a FIND or GET operation for an indexed file, your program 
specifies the index of reference and a key buffer that contains the 
record key. Specify the index of reference in the 1-byte KRF field of 
the RAB, the address of the key buffer in the 1-word KBF field of the 
RAB, and the key size in the 1-byte KSZ field of the RAB. 

A key access FIND or GET operation sets the current-record context to 
the record that is the target of the operation; a key access PUT 
operation leaves the current-record context undefined. 

A key access FIND or PUT operation does not affect the next-record 
context; a key access GET operation sets the next-record context to 
the record following the target record. 

The target of a key access FIND, GET, or PUT operation depends on the 
operation and on the file organization: 

• For a relative file or for a sequential disk file with 
fixed-length records, the key is a positive integer and 
specifies the position of the record in the file. This key is 
the relative record number (RRN) for the record; RRN 1 
specifies the first record, and so forth. 

If your program sets the RB$KGT mask in the 1-word ROP field 
of the RAB, a FIND or GET operation searches for a record 
whose RRN is greater than the given RRN; if it sets the 
RB$KGE mask in the 1-word ROP field of the RAB, the operation 
searches for a record whose RRN is greater than or equal to 
the given RRN; if it sets neither of these masks, the 
operation searches for a record with the given RRN. 
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Note that a FIND, GET, or PUT operation to a relative file or 
to a sequential disk file with fixed length records returns 
the RRN for the target record in the 2-word BKT field of the 
RAB. 

• For a FIND or GET operation to an indexed file, the key 
specifies a record in the file whose record key matches the 
given key. Your program specifies both the key to be matched 
and the file index; the key data type must agree with the key 
data type for the index (string, packed decimal, binary, or 
signed integer) . 

For a string key, your program specifies the portion of the 
key that must be matched. If the value in the 1-byte KSZ 
field of the RAB is nonzero but is smaller than the record 
key, then only that smaller initial portion of the key must 
match . 

If your program sets the RB$KGT mask in the 1-word ROP field 
of the RAB, a FIND or GET operation searches for a record 
whose key is greater than the given key; if it sets the 
RB$KGE mask in the 1-word ROP field of the RAB, the operation 
searches for a record whose key is greater than or equal to 
the given key; if it sets neither of these masks, the 
operation searches for a record whose key exactly matches the 
given key. 

• For a PUT operation to an indexed file, the key (for each 
index) is in the record. The operation has no true target; 
the record is inserted at the proper place and each index is 
updated . 

This targeting and context setting means that although the target of 
the key access operation is a random (selected) record, the record 
context allows subsequent sequential access processing. Therefore 
your program can use key access to "jump" to a selected point in a 
file, then use sequential access to process successive records. 



4.4.3.3 RFA Access - Your program specifies RFA access by setting the 
RB$RFA code in the 1-byte RAC field of the RAB. An RFA access FIND or 
GET operation has as its target the record that your program specifies 
by RFA (record file address) . (The FIND, GET, and PUT operations 
return the RFA for the target record; if your program saves the RFA, 
it can use RFA access for the record in subsequent FIND and GET 
operations.) Specify the RFA in the 3-word RFA field of the RAB. 

An RFA access FIND or GET operation sets the current-record context to 
the record that is the target of the operation. An RFA access FIND 
operation does not affect the next-record context; an RFA access GET 
operation set the next-record context to the record following the 
target record. 

This targeting and context setting means that although the target of 
the RFA access operation is a random (selected) record, the record 
context allows subsequent sequential access processing. Therefore 
your program can use RFA access to "jump" to a selected point in a 
file, then use sequential access to process successive records. 
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4.4.4 Record Buffers 

A PUT or UPDATE operation transfers a record from a record buffer (in 
your program's space) to a file; for a VFC record, the operation also 
transfers the fixed-length portion of the record from a separate 
record header buffer. Your program specifies the address of the 
record buffer in the 1-word RBF field of the RAB and the size of the 
record in the 1-word RSZ field of the RAB; for a VFC record, your 
program also specifies the address of the record header buffer in the 
1-word RHB field of the RAB. 

A GET operation transfers a record from a file to an RMS-11 internal 
I/O buffer and to a user buffer in your program's space. Your program 
specifies the address of the user buffer in the 1-word UBF field of 
the RAB and its size in the 1-word USZ field of the RAB. Along with 
the record, the GET operation returns the address of the record in the 
1-word RBF field of the RAB and its size in the 1-word RSZ field of 
the RAB. 

For a VFC record, a GET operation also transfers the fixed-length 
portion of the record to a separate record header buffer in your 
program's space. Your program specifies the address of the record 
header buffer in the 1-word RHB field of the RAB. 

Exception: if your program specifies locate mode for a GET operation, 
RMS-11 may not transfer the record to the user buffer; see the next 
section for a discussion of locate mode. 



4.4.5 Locate Mode 

The GET and PUT operations normally use RMS-11 internal I/O buffers as 
intermediate storage between your program's buffers (record or user 
buffers) and the file. By specifying locate mode for a GET or PUT 
operation, your program requests RMS-11 to transfer records only 
between its I/O buffers and the file, thus saving time. Your program 
specifies locate mode by setting the RB$LOC mask in the 1-word ROP 
field of the RAB. 

If your program specifies locate mode for a GET operation, RMS-11 may 
transfer the record only to its internal I/O buffer (but not to the 
user buffer). The GET operation routine decides whether to honor the 
locate-mode request or to transfer the record to the user buffer 
anyway; the operation returns the address and size of the retrieved 
record (informing your program of the record's location — the user 
buffer or the I/O buffer) . 

If your program specifies locate mode for a PUT operation, RMS-11 
recognizes that the record may already be in its I/O buffer and if so 
transfers it to the file from there. 

Your program has (in the 1-word RBF field of the RAB) the address of a 
location (in the I/O buffer if possible, otherwise in the user buffer) 
that is suitable for building the next record; this address is 
returned either by a previous locate-mode PUT operation or by an 
initial locate-mode CONNECT operation. Therefore, if you use the 
CONNECT operation for a stream that will use locate-mode PUT 
operations, your program must specify locate mode for the CONNECT 
operation, and must specify a user buffer (the address in the 1-word 
UBF field of the RAB and the size in the 1-word USZ field of the RAB) . 

Note that specifying locate mode for a PUT operation has no effect 
unless the file is sequential, the access mode is sequential, and the 
record format is other than stream record format. 
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4.4.6 Stream Operations 

Stream operations affect stream context and I/O buffers (but not file 
records) . The stream operations for a record stream are: 

• CONNECT: establish a record stream 

• FLUSH: write unwritten buffers for a stream 

• FREE: free locked bucket for a stream 

• NXTVOL: set stream context to beginning of next volume 

• REWIND: set stream context to beginning of current file 

• WAIT: wait for completion of asynchronous operation 

• DISCONNECT: terminate a record stream 
The next sections discuss these operations. 



4.4.6.1 CONNECT Operation - Your program uses the CONNECT operation 
to establish a record stream. (The stream is a record stream because 
your program specified record access for the CREATE or OPEN operation 
for the file.) 

The current-record context after a CONNECT operation is undefined; 
the next-record context is (by default) the first record in the file. 

For an indexed file, your program must specify an initial index of 
reference so that the record context is initialized properly. 

For a sequential file, your program can specify that the initial 
record context is to be at the end-of-file (instead of the beginning 
of the file); in that case, the next-record context after the 
operation is the end-of-file. 

For a sequential disk file, your program specifies the number of 
blocks in the I/O buffer for the stream; for a relative or indexed 
file, your program specifies the number of I/O buffers for the stream. 

If the stream will use locate-mode PUT operations, your program must 
also specify locate mode and supply a user buffer. The CONNECT 
operation returns the address of a location suitable for building the 
first record to be output; see Section 4.4.5. 



4.4.6.2 FLUSH Operation - Your program can use the FLUSH operation to 
write any unwritten buffers for a stream (for example, to increase 
data integrity by ensuring that all changes have been written to the 
file); the FLUSH operation does not affect record context, except 
that the current-record context is undefined for a following TRUNCATE 
or UPDATE operation to a sequential file. 

Note one special case: if the file was opened for deferred writing, 
but not for write sharing, then the buffer may be controlled by 
another record stream and will not be written by the FLUSH operation. 
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4.4.6.3 FREE Operation - Your program can use the FREE operation to 
free a locked bucket for a stream; the FREE operation does not affect 
stream context, except that the current-record context is undefined 
for a following DELETE, TRUNCATE, or UPDATE operation. 



4.4.6.4 NXTVOL Operation - Your program can use the NXTVOL operation 
to advance the context for a stream to the beginning of the next 
magtape volume. The current-record context after the operation is 
undefined; the next-record context is the first record of the new 
volume . 



4.4.6.5 REWIND Operation - Your program can use the REWIND operation 
to reset the context for a stream to the beginning-of-f ile or, for a 
multivolume magtape file, the beginning-of-volume (if it is not the 
first volume of the file) . 

The current-record context after the operation is undefined; the 
next-record context is the first record in the volume (for a 
multivolume magtape file) or the file; for an indexed file, your 
program specifies the index of reference for the operation so that the 
stream context is initialized properly. 



4.4.6.6 WAIT Operation - When your program uses asynchronous 
operation for a stream, it must eventually use the WAIT operation to 
suspend processing until the asynchronous operation has completed; 
the WAIT operation does not affect stream context. 



4.4.6.7 DISCONNECT Operation - Your program can use the DISCONNECT 
operation to terminate a record stream, thus recovering the resources 
committed for the stream (primarily pool space) . The DISCONNECT 
operation also discards record context and the internal stream 
identifier . 



4.4.7 Record Operations 

Record operations affect stream context, buffers (I/O, user, and 
record), and file records. The record operations are: 

• FIND: transfer a record from a file to an I/O buffer 

• GET: transfer a record from a file to an I/O buffer and to a 
user buffer 

• PUT: transfer a record from a user buffer to a file 

• DELETE: remove a record from a file 

• UPDATE: replace a record in a file 

• TRUNCATE: remove the current record and all following records 
from a sequential file 

The next sections discuss these operations. 
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4.4.7.1 FIND Operation - Your program can use the FIND operation to 
transfer a record (or part of a record) from a file to an I/O buffer; 
the FIND operation does not transfer the record to a user buffer. 

Your program specifies an access mode (sequential, key, or RFA) for 
the FIND operation; Section 4.4.3 describes the target record and 
context-setting for the FIND operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access, and 4.4.3.3 for RFA access). 

For a relative file or for a sequential disk file with fixed-length 
records, the FIND operation returns the relative record number (RRN) 
and the record file address (RFA) for the found record; for other 
files, the FIND operation returns only the RFA for the found record. 



4.4.7.2 GET Operation - Your program can use the GET operation to 
transfer a record from a file to an I/O buffer and to a user buffer 
(which your program specifies). 

Your program specifies an access mode (sequential, key, or RFA) for 
the GET operation; Section 4.4.3 describes the target record and 
context-setting for the GET operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access, and 4.4.3.3 for RFA access). 

The GET operation returns the address and size of the retrieved 
record, along with its RFA; for a relative file or for a sequential 
disk file with fixed-length records, the GET operation also returns 
the RRN for the retrieved record. 

If your program specifies locate mode for the GET operation, it must 
also specify a user buffer; see Section 4.4.5. 



4.4.7.3 PUT Operation - Your program can use the PUT operation to 
transfer a record from a user buffer to an I/O buffer and to a file. 

Your program specifies an access mode (sequential or key) for the PUT 
operation; Section 4.4.3 describes the target record and 
context-setting for the PUT operation (Section 4.4.3.1 for sequential 
access, 4.4.3.2 for key access). 

Your program can specify that RMS-11 must honor bucket fill numbers. 

For an indexed file, your program can specify that each PUT operation 
in a series is part of a mass insertion; for a relative file, your 
program can specify that the PUT operation should overwrite the target 
record (if any) . 

The PUT operation returns the RFA for the inserted record; for a 
relative file or for a sequential disk file with fixed-lentgh records, 
the PUT operation also returns the RRN for the inserted record. 

If your program specifies locate mode for the PUT operation, it must 
also specify a user buffer. The PUT operation returns the address of 
a location suitable for building the next output record; see Section 
4.4.5. 
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4.4.7.4 DELETE Operation - Your program can use the DELETE operation 
to remove a record from a relative or indexed file. The target of a 
DELETE operation is the current record. 

The current-record context after a DELETE operation is undefined; the 
next-record context is unchanged. 

For an indexed file, your program can specify that RMS-11 must use the 
fast-deletion procedure. However, this procedure is faster because it 
deletes only those alternate index pointers that it must; future 
retrieval operations may be slowed by the presence of undeleted 
alternate index pointers. 



4.4.7.5 UPDATE Operation - Your program can use the UPDATE operation 
to transfer a record from a user buffer to a file (overwriting the 
existing record) . The target of the UPDATE operation is the current 
record, which is overwritten. 

The current-record context after an UPDATE operation is undefined; 
the next-record context is unchanged. 

Your program specifies the record buffer for the record to be inserted 
(and, for a VFC record, the VFC-header buffer). 



4.4.7.6 TRUNCATE Operation - Your program can use the TRUNCATE 
operation to remove the current record and all following records 
(through the end-of-file) from a sequential file. The current-record 
context after a TRUNCATE operation is undefined; the next-record 
context is the new end-of-file. 



4.5 BLOCK PROCESSING 

This section describes use of RMS-11 block processing. Its 
subsections are: 

• Block streams: the paths from your program to file blocks 

• Block context: the "current location" of a stream in a file 

• Block access modes: the ways your program can access blocks 

• Block buffers: the locations of blocks in your program's 
space 

• Stream operations: stream operations for a block stream 

• Block operations: operations that access blocks 



4.5.1 Block Streams 

A block stream is a path from your program to the blocks in a file. 
Your program establishes a block stream when it uses the CONNECT 
operation to connect a stream to a file (opened for block access by an 
earlier CREATE or OPEN operation) . A block stream supports stream 
operations and block operations, but not record operations. 
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4.5.2 Block Context 

A block stream has a block context, which consists of a readable-block 
context and a writable-block context. The READ operation uses the 
readable-block as its target block; the WRITE operation uses the 
writable-block as its target block; block operations change both the 
readable-block and the writable-block contexts. 

For a disk file, your program can use the READ or WRITE operation to 
read or write multiple blocks in a single operation. In that case, 
reading or writing begins at the readable block or the writable block 
(respectively), and continues through the number of blocks requested. 



4.5.3 Block Access Modes 

The block operations READ and WRITE allow your program to specify a 
block access mode (in the 2-word BKT field of the RAB) ; the block 
access mode determines the target block for the operation. The block 
access modes are: 

• Sequential access 

• VBN access 

For a magtape file, your program can use either sequential block 
access or VBN access; however, the program must access one block at a 
time, and in sequential order (unless it uses the SPACE operation to 
position the magtape). 

The next sections discuss these access modes. 



4.5.3.1 Sequential Access - Your program specifies sequential block 
access by giving the value in the 2-word BKT field of the RAB. A 
sequential access READ operation has as its target the readable block; 
it sets the readable-block context to the nex t- fol lowing unread block, 
and sets the writable-block context to the target block (first block 
read for that READ operation) . 

A sequential access WRITE operation has as its target the writable 
block; it sets both the readable-block and writable-block contexts to 
the next-following unwritten block. 

This targeting and context setting has the following results: 

• A series of sequential access READ operations reads successive 
blocks . 

• A series of sequential access WRITE operations writes 
successive blocks. 

• A series of paired READ and WRITE operations updates 
successive blocks. 
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4.5.3.2 VBN Access - A VBN access READ or WRITE operation reads or 
writes blocks beginning with a virtual block that your program 
specifies. Specify the virtual block number in the 2-word BKT field 
of the RAB. 

Note that your program can use VBN access to move to a random position 
in a disk file, and then use sequential block access to process blocks 
sequentially from that point. 



4.5.4 Block Buffers 

Your program specifies a user buffer for the READ operation; the 
operation returns the address of the first-read byte and the number of 
bytes read. Specify the address of the user buffer in the 1-word UBF 
field of the RAB and its size in the 1-word USZ field of the RAB; the 
READ operation returns the address of the first-read byte in the 
1-word RBF field of the RAB and the number of bytes read in the 1-word 
RSZ field of the RAB. 

Your program specifies the buffer containing the writable data for the 
WRITE operation. Specify the buffer address in the 1-word RBF field 
of the RAB and its size in the 1-word RSZ field of the RAB. 



4.5.5 Stream Operations 

Stream operations affect stream context and I/O buffers (but not file 
blocks). The stream operations for a block stream are: 

• CONNECT: establish a block stream 

• FREE: free a locked block for a stream 

• WAIT: wait for completion of asynchronous operation 

• DISCONNECT: terminate a block stream 
The next sections discuss these operations 



4.5.5.1 CONNECT Operation - Your program uses the CONNECT operation 
to establish a block stream. (The stream is a block stream because 
your program specified block access for the CREATE or OPEN operation 
for the file.) 

After a CONNECT operation, both the readable-block and writable-block 
contexts are the first block in the file. 



4.5.5.2 FREE Operation - Your program can use the FREE operation to 
free a locked block for a stream; the FREE operation does not affect 
stream context. 
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4.5.5.3 WAIT Operation - When your program uses asynchronous 
operation for a stream, it must eventually use the WAIT operation to 
suspend processing until the asynchronous operation has completed; 
the WAIT operation does not affect stream context. 



4.5.5.4 DISCONNECT Operation - Your program can use the DISCONNECT 
operation to terminate a block stream, thus recovering the resources 
committed for the stream. The DISCONNECT operation also discards 
block context and the internal stream identifier. 



4.5.6 Block Operations 

Block operations affect stream context, block buffers, and file 
blocks. The block operations are: 

• READ: transfer blocks from a file to a block buffer 

• WRITE: transfer blocks from a block buffer to a file 

• SPACE: set block context for a magtape file 
The next sections discuss these operations. 



4.5.6.1 READ Operation - Your program can use the READ operation to 
transfer blocks from a file to a block buffer. Your program specifies 
an access mode (sequential or VBN) for the READ operation; Section 
4.5.3.1 describes sequential access; Section 4.5.3.2 describes VBN 
access . 



4.5.6.2 WRITE Operation - Your program can use the WRITE operation to 
transfer blocks from a block buffer to a file. Your program specifies 
an access mode (sequential or VBN) for the WRITE operation; Section 
4.5.3.1 describes sequential access; Section 4.5.3.2 describes VBN 
access . 

Note that because the WRITE operation always writes to the file 
immediately, the FLUSH operation has no use for block access. 



4.5.6.3 SPACE Operation - Your program can use the SPACE operation to 
set block context for a magtape file; the context is moved forward or 
backward the specified number of blocks. After a SPACE operation, 
both the readable-block and writable-block contexts are the specified 
block . 
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OPERATION MACRO DESCRIPTIONS 



This chapter describes RMS-11 operation macros and the operation 
routines they call. Each section of the chapter describes an 
operation macro and its corresponding operation. (For the $FIND, 
$GET , $PUT, $READ, and $WRITE macros, there is a separate description 
for each access method.) 

Each description is divided into the following parts: 

• FORMAT - the format for the macro and its parameters 

• CONTROL BLOCKS - the required and optional control blocks for 
the operation 

• OPTIONS - the options that you can select for the operation, 
and the control block fields and values that control the 
options 

• STREAM CONTEXT - the current-record and next-record contexts 
(for a record stream) or the readable-block and writable-block 
contexts (for a block stream) after the operation completes 

• RETURNED VALUES - the values that the operation routine 
returns in control block fields and buffers 

• CHECKLISTS - a list of the control block fields that you 
supply to specify options, and a list of the control block 
fields that contain returned values 

The operation macros are: 

• $CLOSE - Close an open file 

• $CONNECT - Connect a record stream to an open file 

• $CREATE - Create a new file and open it for processing 

• $DELETE - Remove a record from a file 

• $DISCONNECT - Disconnect a record stream 

• $DISPLAY - Write file data into control block fields 

• $ENTER - Enter a file specification into a directory 

• $ERASE - Erase an existing file 

• $EXTEND - Extend the allocation for an open file 

• $FIND - Set the stream context to a record in a file 
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• $FLUSH - Write any unwritten buffers for a stream 

• $ FREE - Unlock a bucket locked by a stream 

• $GET - Retrieve a record from a file 

• $NXTVOL - Set stream context to the beginning of the next 
magtape volume 

• $OPEN - Open an existing file 

• $PARSE - Write file data into a NAM block 

• $PUT - Insert a record into a file 

• $READ - Read blocks from a file 

• $REMOVE - Delete a file specification from a directory 

• $RENAME - Rename an existing file 

• $ REWIND - Set stream context to beginning-of-f i le 

• $SEARCH - Search directories for a file specification 

• $SPACE - Move magtape block stream context forward or backward 

• $TRUNCATE - Remove all following records from a file 

• $UPDATE - Replace a record in a file 

• $WAIT - Wait for asynchronous completion for stream 

• $WRITE - Write blocks into a file 
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5.1 $CLOSE MACRO 

The $CLOSE macro calls the CLOSE operation routine to close an open 
file . 



FORMAT 

The format for the $CLOSE is: 

:?CLOSE f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the CLOSE operation. 

If you supply a PRO block, the CLOSE operation reads its fields to 
obtain new owner and protection codes for the file. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the CLOSE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



Internal File Identifier 

The CLOSE operation reads the internal file identifier for the file 
from the 1-word IFI field of the FAB. This identifier was written by 
the CREATE or OPEN operation when the file was opened. 



File Owner and Protection 

If you want to change the owner of the target file, specify the 
project (or group) portion of the owner code in the 1-word PRJ field 
of the PRO block, and specify the programmer (or member) portion in 
the 1-word PRG field of the PRO block; if you specify for both 
these fields, the PRO block (including the PRO field) is ignored. 

If you want to change the file protection for the target file, specify 
the protection code in the 1-word PRO field of the PRO block (and 
specify a nonzero value in the PRG or PRJ field); if you specify in 
this field, the operating system uses its defaults. 
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Rewinding Magtape 

For a magtape file, if you want the magtape rewound when the file is 
closed, set the FB$RWC mask in the 1-word FOP field of the FAB . Note 
that if the FB$RWC mask was set when the file was opened (by the 
CREATE or OPEN operation) , setting the mask has no effect for the 
CLOSE operation. 



STREAM CONTEXT 

The CLOSE operation destroys stream context for any streams connected 
by the closing file (after writing any unwritten buffers for those 
streams) . 



RETURNED VALUES 



Private Buffer Pool 

The CLOSE operation writes the address of the private buffer pool (if 
any) for the file in the 1-word BPA field of the FAB; if the CLOSE 
operation clears the BPA field, the file had no private buffer pool. 

If the file had a private buffer pool, the CLOSE operation writes the 
size (in bytes) of the pool in the 1-word BPS field of the FAB, or 
clears this field if the file did not use a private buffer pool. 



Internal File Identifier 

The CLOSE operation clears the 1-word IFI field of the FAB. 



Completion Status and Value 

The CLOSE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-1 lists control block fields that are input to the CLOSE 
operation. Table 5-2 lists control block fields that are output by 
the CLOSE operation. 
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Table 5-1: CLOSE Input Fields 
Block Field Description 



ALL AID Area number 

ALL NXT Next XAB address 

DAT NXT Next XAB address 

FAB FOP File processing option mask 

FB$RWC Rewind magtape after closing file 

FAB IFI Internal file identifier 

FAB XAB XAB address 

KEY REF Index reference number 

KEY NXT Next XAB address 

PRO NXT Next XAB address 

PRO PRG Programmer or member portion of file owner code 

PRO PRJ Project or group portion of file owner code 

PRO PRO File protection code 

SUM NXT Next XAB address 



Table 5-2: CLOSE Output Fields 



Block Field Description 



FAB 


BPA 


Private buffer pool address 


FAB 


BPS 


Private buffer pool size (bytes) 


FAB 


IFI 


Internal file identifier 


FAB 


STS 


Completion status code 


FAB 


STV 


Completion status value 
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5.2 $CONNECT MACRO 

The $CONNECT macro calls the CONNECT operation routine to connect a 
record stream to an open file, and initialize the stream context. 



FORMAT 

The format for the $CONNECT is: 

$CONNECT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the CONNECT operation. 
You must supply a FAB for the CONNECT operation. 



OPTIONS 



File Identification 

Specify the address of the FAB in the 1-word FAB field of the RAB. 
The CONNECT operation reads the internal file identifier for the file 
from the 1-word IFI field of the FAB. 



I/O Buffers 

For a sequential disk file, specify the size (in blocks) of the RMS-11 
I/O buffer for the stream in the 1-byte MBC field of the RAB; the 
largest legal value is 63. If you specify 0, the CONNECT operation 
uses a buffer of one block. For a relative file, an indexed file, or 
a sequential nondisk file, the CONNECT operation ignores the MBC 
field. 

For a relative or indexed file, specify the number of I/O buffers for 
the stream in the 1-byte MBF field of the RAB. For a sequential file, 
specify in the MBF field. If you specify 0, the CONNECT operation 
uses the minimum number of buffers: one for a sequential or relative 
file, or two for an indexed file. 



User Buffer (Locate Mode for Sequential File) 

If you are connecting to a sequential file, and if you intend to 
execute PUT operations in locate mode for the connected stream, then: 

• Specify the address of the user buffer in the 1-word UBF field 
of the RAB. 

• Specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

• Set the RB$LOC mask in the 1-word ROP field of the RAB. 
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This assures proper handling of the first PUT operation for the 
stream . 



Key of Reference (Indexed File) 

For an indexed file, specify the key of reference in the 1-byte KRF 
field of the RAB. This value specifies the index to be used in 
establishing initial record context: for the primary index, 1 for 
the first alternate index, and so forth. 



Initial Stream Context (Sequential File) 

If you want to initialize the next-record context of a sequential file 
to the end-of-file, set the RB$EOF mask in the 1-word ROP field of the 
RAB; if you do not set this mask, the CONNECT operation initializes 
the next-record context to the first record in the file (or to the 
end-of-file if the file is empty) . 



Asynchronous Operation 

If you want to execute the CONNECT operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the CONNECT operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

For a record-access file, the current-record context after a CONNECT 
operation is undefined; the next-record context is the first record 
in the file (under the specified index for an indexed file), or the 
end-of-file, if the file is empty. 

For a block-access file, both the readable-block and writable-block 
contexts after a CONNECT operation are the first block in the file. 



RETURNED VALUES 



Internal Stream Identifier 

The CONNECT operation writes an internal stream identifier in the 
1-word ISI field of the RAB. Do not destroy this identifier; all 
otheir stream, record, and block operation routines read it. 



Record Buffer 

The CONNECT operation copies the value from the UBF field into the 
1-word RBF field of the RAB (the record address) ; this prepares the 
record buffer for your use in case the first record operation for the 
stream is a locate-mode PUT operation to a sequential file. 



RFA 

For block access, the CONNECT operation returns the logical 
end-of-file value in the 3-word RFA field of the RAB. The first two 
words of this field are the VBN in which the logical end-of-file 
occurs, and the third word is the offset of the first byte beyond the 
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logical end-of-file within that block. This logical end-of-file value 
is meaningful only for disk files. 



Completion Status and Value 

The CONNECT operation returns completion status in the 1-word STS 
field of the RAB and returns a completion value in the 1-word STV 
field of the RAB. Appendix A lists completion status symbols and 
values . 



CHECKLISTS 

Table 5-3 lists control block fields that are input to the CONNECT 
operation. Table 5-4 lists control block fields that are output by 
the CONNECT operation. 



Table 5-3: CONNECT Input Fields 
Block Field Description 



FAB IFI Internal file identifier 

RAB FAB FAB address 

RAB KRF Key of reference 

RAB MBC Multiblock count 

RAB MBF Multibuffer count 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$EOF Position to end-of-file 
RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-4: CONNECT Output Fields 
Block Field Description 



RAB 


ISI 


Internal stream identifier 


RAB 


RBF 


Record buffer address 


RAB 


RFA 


End-of-file address 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.3 $CREATE MACRO 

The $CREATE macro calls the CREATE operation routine to create a new 
file and open it for processing. 

FORMAT 

The format for the $CREATE is: 

$CREATE f abaddr [ , [erraddr ] [ , sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the CREATE operation. 

If you supply a NAM block, the CREATE operation reads its fields to 
obtain the expanded string buffer, and writes identifiers in its 
fields . 

To supply a NAM block for the CREATE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

Each ALL block that you supply defines one area in the created file, 
and you can place the area at a specific location. If you supply no 
ALL blocks, the file has one area; you define this area in the FAB, 
but you cannot place the area at a specific location. You cannot 
supply more than one ALL block for a sequential or relative file. 

Each KEY block that you supply defines one index for the created file. 
You must supply at least one KEY block for an indexed file; you 
cannot supply KEY blocks for a relative or sequential file. 

If you supply a PRO block, the CREATE operation reads its fields to 
obtain the protection for the file. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the CREATE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers must be consecutive 
beginning with 0. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers must be consecutive beginning with 
0.. 

Multiple DAT, PRO, or SUM XABs are illegal. 

Note that if the LAN field of a KEY XAB is 0, RMS-11 will use the area 
specified in the IAN field for the lowest level index for that index. 
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OPTIONS 



File Specification 



The CREATE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string). 



RMS-11 defaults are: 



• Device -- The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory -- The current directory for the task. 

• Name, type, version -- Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 

FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 

field of the FAB; if you specify in the FNS field, the CREATE 
operation uses no file string. 



Specify the address of the default string in 
the FAB. Specify the size (in bytes) of 
1-byte DNS field of the FAB; if you specify 
CREATE operation uses no default string. 



the 1-word DNA field of 
the default string in the 
in the DNS field, the 



If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the CREATE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 



In the same circumstance, the CREATE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged s tr i ng . 



Expanded String Buffer 

If you want the CREATE operation to return the expanded string for the 
created file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block 
and its size (in bytes) in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the CREATE operation does not return 
the expanded string. 



Supersession of Existing File 

If you want to create a file that supersedes an existing file with the 
same specification, set the FB$SUP mask in the 1-word FOP field of the 
FAB; if you do not set the FB$SUP mask, and you specify a file that 
already exists, the CREATE operation returns an error completion and 
does not create the new file. 
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Temporary or Marked-f or-Delete File 

If you want the created file to be a temporary file (one that has no 
directory entry) , set the FB$TMP mask in the 1-word FOP field of the 
FAB; if you do not set the FB$TMP mask, the created file has a 
directory entry. 

If you want the created file to be deleted when it is closed, set the 
FB$MKD mask in the 1-word FOP field of the FAB; this causes the 
operating system to delete the file when it has no accessing programs. 
If you do not set the FB$MKD mask, the created file is not marked for 
deletion . 

If you want the created file to be a temporary file that is marked for 
deletion, set the FB$TMD mask in the 1-word FOP field of the FAB; the 
FB$TMD mask includes the bits for both the FB$TMP and the FB$MKD 
masks . 



File Protection 

Specify the protection for the created file in the 1-word PRO field of 
the PRO block; if you supply no PRO block, the operating system uses 
its default file protection. 



File Organization 

Specify a file organization code in the 1-byte ORG field of the FAB. 
The symbols for file organization codes are: 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 



Record Format 



Specify the record format code in the 1-byte RFM 
The symbols for record format codes are: 



field of the FAB 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 



If you specify VFC record format (FB$VFC code in the RFM field) , 
specify the size (in bytes) of the VFC header field in the 1-byte FSZ 
field of the FAB; if you specify 0, the CREATE operation uses the 
value 2. 



Blocked Records 

If you are creating a sequential disk file, and if you want the file 
to contain blocked records (records that cannot span block 
boundaries) , set the FB$BLK mask in the 1-byte RAT field of the FAB; 
if you do not set the FB$BLK mask, records can span block boundaries. 
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If you are creating a relative or indexed file, the FB$BLK mask has no 
effect on storage of records in the file. However, this mask will be 
preserved and returned on OPEN operations. The FB$BLK mask is ignored 
for files on unit-record devices. 

Note that records are always blocked in a magtape file, regardless of 
the FB$BLK setting. 



Record-Output Handling 

Specify a record-output mask in the 1-byte RAT field of the FAB. This 
record-output attribute controls the handling of records that are 
output to a unit-record device: 

• FORTRAN-style record-output specifies FORTRAN-style 
carriage-control handling. 

• Carriage-return record-output specifies that a prefixed 
linefeed and a suffixed carriage-return must be added to each 
record on output to a print device. 

• Print-format record-output specifies that the file is in print 
format. This format is allowed only for files with VFC 
records for which the fixed header size for each record is 
or 2 bytes. (RMS-11 treats a header size of as if you had 
specified 2.) 

When records from the file are written directly to a 
unit-record device, RMS-11 interprets the first byte of the 
VFC header as a prefix for the record and the second byte of 
the header as a suffix for the record. RMS-11 further 
interprets the prefix/suffix control bytes as follows: 

If the top bit of the control byte is clear, the entire byte 
is used as a count of the number of carriage return/line feed 
pairs with which to prefix or suffix the record. 

If the top bit of the control byte is set, the low 5 bits of 
the byte are used as the prefix or suffix character. 

If you specify none of these attributes, records are output to 
unit-record devices without special handling. 

If you are creating a file on a device other than a unit-record 
device, the record output mask has no effect on storage of records in 
the file. However, this mask will be preserved and returned on OPEN 
operations . 

The symbols for record-output masks are: 

FB$CR Add CRLF to print record ( LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 



Record Size 

Specify the record size (in bytes) in the 1-word MRS field of the FAB 

(unless you have specified undefined record format). For fixed-length 

records, the CREATE operation uses this value as the record size; for 

variable-length records, the CREATE operation uses this value as the 
maximum record size; for VFC records, the CREATE operation uses this 

value as the maximum size of the variable portion of each record. 
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If you specify a nonzero value in the MRS field, RMS-11 checks the 
size of each record written to the file against the MRS-field value, 
and returns an error completion if the record size is inappropriate; 
if you specify in the MRS field, RMS-11 does not check record sizes 
against the MRS-field value. 



Maximum Record Number 

If you specify relative file organization (FB$REL value in the ORG 
field) , specify the maximum record number in the 2-word MRN field of 
the FAB. If you specify a nonzero value in the MRN field, RMS-11 
checks the record number of each record written to the file against 
the MRN-field value, and returns an error completion if the record 
number is too large; if you specify in the MRN field, RMS-11 does 
not check record numbers against the MRN-field value. 



Private Buffer Pool 

If you want the CREATE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the CREATE 
operation uses the central buffer pool. 

The pool that the CREATE operation uses is also used by the DISPLAY 
and EXTEND operations, and by stream and record operations while the 
file is open. 



Logical Channel 

Specify the logical channel for the CREATE operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 

The logical channel that the CREATE operation uses is also used by the 
DISPLAY and EXTEND operations, and by stream and record or block 
operations while the file is open. 



Retrieval Pointers 

Specify the number of retrieval pointers for the open file in the 
1-byte RTV field of the FAB. If you specify 0, the CREATE operation 
uses the operating system default; if you specify -1, the CREATE 
operation maps as much of the file as possible. 
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Requested Access 

Specify one or more reques ted-access masks in the 1-byte FAC field of 
the FAB. This mask determines the access that the creating program 
has while the file is open. Regardless of what you specify, the 
CREATE operation includes the mask FB$PUT (for record access) or 
FB$WRT (for block access). The symbols for requested-access masks 
are : 



FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PQT Request put access 

FB$REA Request block read access 

FB$TRN Request f i nd/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 



Note that FB$REA and FB$WRT override any record access requested. 



Access Sharing 

Specify the kinds of access that your program is willing to share with 
other programs by setting an access-sharing mask in the 1-byte SHR 
field of the FAB. The symbols for access-sharing masks are: 



FB$GET Share find/get access 

FB$NIL No access sharing 

FB$WRI Share find/get/put/update/delete access 

FB$UPI Share any access (user-provided interlock) 

The kinds of access sharing are: 



• Shared read access 



Your program is willing to allow other programs to read the 
file, but not to write it. 



• Shared write access 



Your program is willing to allow other programs to both read 
and write the file. Shared write access is not allowed for a 
sequential file unless the file has undefined record format 
and your program opens the file for block access; shared 
write access is also not allowed for a relative or indexed 
file that your program opens for block access. In such cases, 
RMS-11 automatically converts the shared write access 
specification to a shared read access specification 
internally. 



• No shared access 



Your program is not willing to allow other programs to either 
read or write the file. RMS-11 does, however, allow other 
programs to read the file unless your program also requests 
some form of write access (which is always the case for 
CREATE) . 

• User-provided interlocking 

Your program and other cooperating programs define and enforce 
their own access interlocking; RMS-11 does not check access 
sharing. User-provided interlocking is allowed only for 
sequential disk files; otherwise, the FB$UPI mask is ignored 
(but other masks are honored) . 
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Deferred Writing 

If you want deferred buffer writing for the open file, set the FB$DFW 
mask in the 1-word FOP field of the FAB; This means that RMS-11 does 
not necessarily write its buffers during a write-type operation 
(DELETE, PUT, or UPDATE) , but instead writes buffers only when it 
needs them for other operations (or when your program executes the 
FLUSH operation for the stream) . 

If you do not set the FB$DFW mask, the DELETE, PUT, and UPDATE 
operations write buffers to the file immediately. 

Note that record operations always use a form of deferred buffer 
writing for sequential files, and that block operations never use 
deferred buffer writing. Therefore you need only decide whether to 
use deferred writing for a record stream to a relative or indexed 
file,. 



File Locking 

If you want the file to remain unlocked even if it is closed 
abnormally, set the FB$DLK mask in the 1-word FOP field of the FAB; 
if you do not set the FB$DLK mask, the operating system locks the file 
if it is closed abnormally. 



Magtape Block Size 

If you are creating a magtape file, specify the block size (in 
characters) for the file in the 1-word BLS field of the FAB. If you 
specify 0, RMS-11 uses the default block size for the device. If you 
specify a nonzero value, it must be in the range 18 through 8192. 



Magtape Positioning 

You can position a magtape file on its magtape. To position the file 
at the beginning of the magtape (overwriting all files on the tape), 
set the FB$RWO mask in the 1-word FOP field of the FAB. To position 
the file at the end of the last-closed file (overwriting any following 
files) , set the FB$POS mask in the 1-word FOP field of the FAB. If 
you set neither of these masks, the CREATE operation positions the 
file at the end of the last file on the magtape (overwriting nothing). 



Rewinding Magtape on Close 

If you want the magtape rewound when the created file is closed, set 
the FB$RWC mask in the 1-word FOP field of the FAB. If you do not set 
this mask, the magtape will not be rewound on close unless you set the 
FB$RWC mask for the CLOSE operation. Note, however, that if you set 
the FB$RWC mask for the CREATE operation, the magtape will be rewound 
even if you do not set the FB$RWC mask for the CLOSE operation. 
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Single-Area Unlocated File 

If you want the created file to have only one area, and if you do not 
want to place the area at a specific location on disk, then you supply 
no ALL blocks for the CREATE operation, but rather specify the 
following file attributes in FAB fields (as described in sections 
below) : 

• File allocation size 

• Default file extension size 

• File bucket size 

• File contiguity 



Multiarea or Located File 

If you want to place the created file at a specific location on disk, 
or if you want a created indexed file to have more than one area, then 
you supply ALL blocks for the CREATE operation and you specify the 
following area attributes in ALL block fields (as described in 
sections below) : 



• 


Area allocation size 


• 


Default area extension size 


• 


Area bucket size 


• 


Area contiguity 


• 


Area alignment 


• 


Area location 



Specify the area number for each area in the 1-byte AID field of the 
ALL block for the area. 

Sequential and relative files are permitted to have only a single 
area: area 0. Thus, for these files, the information in the (single) 
ALL block describes the file as a whole, overriding any corresponding 
information in the FAB. 

Similarly, block-accessed indexed files are treated without regard for 
their internal (logical) structure. In this case, only a single ALL 
block is permitted, and its contents describe the file as a whole, 
overriding any corresponding information in the FAB. 

Symmetric treatment of ALL blocks by the OPEN operation facilitates 
block-access COPY operations, which are independent of file 
organi zat ion . 



Allocation Size 

For a single-area unlocated file, specify the file allocation size (in 
blocks) in the 2-word ALQ field of the FAB. For a multiarea or 
located file, specify the area allocation size (in blocks) in the 
2-word ALQ field of the ALL block for each area. 
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Default Extension Size 

For a single-area unlocated file, specify the default extension size 
(in blocks) for the file in the 1-word DEQ field of the FAB. For a 
multiarea or located file, specify the default extension size (in 
blocks) for each area in the 1-word DEQ field of the ALL block for the 
area ,. 



Bucket Size (Relative or Indexed File) 

For a single-area unlocated file, specify the bucket size (in blocks) 
for the file in the 1-byte BKS field of the FAB. For a multiarea or 
located file, specify the bucket size (in blocks) for each area in the 
1-byte BKZ field of the ALL block for the area. 

The largest allowed bucket size is 32 blocks; the smallest is 0. If 
you specify a bucket size of 0, the CREATE operation uses 1-block 
buckets for the file or area. 



Area Location 

If you want to place an area at a particular location on disk, specify 
an alignment mask in the 1-byte ALN field of the ALL block for the 
area. Logical block alignment places the area at a specified logical 
block; virtual block alignment (not allowed for area 0) places the 
area near a specified virtual block. If you specify no alignment 
mask, the CREATE operation places the area at any convenient location. 
The symbols for alignment masks are: 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Specify the number of the logical block or virtual block in the 2-word 
LOC field of the ALL block for the area. 

If you do not want the file to be created unless the specified area 
location is available, set the XB$HRD mask in the 1-byte AOP field of 
the ALL block for the area. If you do not set this mask, the CREATE 
operation creates the file even if it must place the area at an 
alternate location. Note that hard location at a virtual block 
location is illegal. 

The CREATE operation creates areas by extending the file if either of 
the following is true: 

• You specify placement for areas other than area (in which 
case the CREATE operation ignores the FB$CTG mask) . 

• You specify contiguity in one or more ALL blocks, but not in 
the FAB for the file. 

Otherwise the CREATE operation creates the entire file as a single 
operation, and, if you specified contiguity in the FAB, creates the 
entire file as a single contiguous extent. 
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Contiguity 

If you want a file to be contiguous, set the FB$CTG mask in the 1-word 
FOP field of the FAB and (for a multiarea file) do not specify disk 
location for any area except (optionally) area 0; if the CREATE 
operation cannot create a contiguous file, it returns an error 
completion; if you do not set this mask, the CREATE operation does 
not attempt to create a contiguous file. 

If you want an area of a multiarea or located file to be contiguous, 
set the XB$CTG mask in the 1-byte AOP field of the ALL block for the 
area. If you set this mask and the CREATE operation cannot create a 
contiguous area, it returns an error completion; if you do not set 
this mask, the CREATE operation does not attempt to create a 
contiguous area. 



Indexes 



If you specify indexed file organization (FB$IDX value in the ORG 
field) , you must supply at least one KEY block for the CREATE 
operation, unless you are using block access (in which case, any KEY 
blocks are ignored) . Each KEY block you supply defines one index for 
the created file. 



Specify the reference number for each index in the 1-byte REF field of 
the KEY block for the index. Specify for the primary index, 1 for 
the first alternate index, and so forth. Chain KEY blocks so that the 
reference numbers are in consecutive order, and so that there are no 
intervening XABs of other types (ALL, DAT, PRO, or SUM blocks). 



Key Name 



If you want to define a key name for the index, place the key name 
string in a 32-character buffer. Specify the address of this buffer 
in the 1-word KNM field of the KEY block for the index. If you 
specify in the KNM field, the index has no key name. 



Index Key Data Type 



Specify a key data type code in the 1-byte DTP field of the KEY block 
for each index. The symbols for key data type codes are: 



XB$BN2 16-bit 

XB$BN4 32-bit 

XB$IN2 15-bit 

XB$IN4 31-bit 

XB$PAC Packed 

XB$STG String 



unsigned integer 
unsigned integer 
signed integer 
signed integer 
decimal number 



Key Segments 

Specify the size and position of each key segment in the 8-byte SIZ 

field of the KEY block and the 8-word POS field of the KEY block for 

the index. (Only a string key can have more than one segment.) 
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The first byte of the SIZ field is for the size (in bytes) of the 
first key segment, the second byte is for the second segment, and so 
forth. If the key is to have fewer than eight segments, specify in 
the remaining bytes of the SIZ field. (The CREATE operation does not 
check segment sizes after the first it encounters in the SIZ field.) 

The first word of the POS field is for the position of the first key 
segment, the second word is for the second segment, and so forth. If 
the key has fewer than eight segments, the CREATE operation ignores 
the remaining words of the POS field. (The first position in a record 
is position 0.) 



Key Changes 

For an alternate index, if you want to allow the key to change during 
update operations, set the XB$CHG mask in the 1-byte FLG field of the 
KEY block and the XB$DUP mask in the 1-byte FLG field of the KEY block 
for the index; if you do not set these masks, RMS-11 returns an error 
if a program attempts to change the value of a record key during 
updating .. 



Key Duplications 

If you want to allow duplicate keys in an index, set the XB$DUP mask 
in the 1-byte FLG field of the KEY block for the index. If you do not 
set this mask, RMS-11 returns an error if a program attempts to insert 
or update a record that would create a duplicate record key. Note 
that the XB$DUP mask must be set if record keys in the index are to be 
changeable during update. 



Null Keys 

If you want to omit null keys from an alternate index, set the XB$NUL 
mask in the 1-byte FLG field of the KEY block for the index, and (for 
a string key) specify the null character for the key in the 1-byte NUL 
field of the KEY block (the null value for a nonstring key is 0) . 

If you do not set the XB$NUL mask, all keys are included in the index; 
if you set the XB$NUL mask, a nonstring key with a value or a string 
key with an all-null value will not appear in that alternate index. 



Index Areas 

Specify areas for the data records and for the levels of the index: 

• The area for data records in the 1-byte DAN field of the KEY 
block 

• The area for the lowest index level in the 1-byte LAN field of 
the KEY block 

• The area for higher index levels in the 1-byte IAN field of 
the KEY block 

Note that the bucket sizes of the LAN and IAN areas of a given index 
must be identical. 
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Bucket Fill Numbers 

Bucket fill numbers guide the PUT and UPDATE operations in deciding 
how many records to place in each bucket. A bucket fill number of 
is usually appropriate, and specifies that buckets should be filled 
completely . 

A nonzero bucket fill number specifies the number of bytes that should 
be filled in each bucket. If the specified bucket fill number is less 
than half the bucket size, it is rounded up to half the bucket size; 
if the specified number is more than the bucket size, it is rounded 
down to the bucket size. 

Specify the fill numbers for data buckets and index buckets: the fill 
number for data buckets in the 1-word DFL field of the KEY block, and 
the fill number for index buckets in the 1-word IFL field of the KEY 
block . 



Longest Record Length 

If you specify block access for the created file, and you plan to copy 
an existing file into the new file, you can specify the length of the 
longest record in the new file in the 1-word LRL field of the FAB. 



RETURNED VALUES 



Internal File Identifier 

The CREATE operation writes an internal file identifier in the 1-word 
IFI field of the FAB. (The CLOSE operation clears the internal file 
identifier .) 

The CLOSE, CONNECT, DISPLAY, and EXTEND operations read the internal 
file identifier; do not alter the IFI field while the file is open. 



Device Characteristics 

The CREATE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MD I mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 
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Device, Directory, and File Identifiers 

If you supply a NAM block, the CREATE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the CREATE operation writes the file 
specification for the created file in this buffer, and writes the 
length (in bytes) of the specification string in the 1-byte ESL field 
of the NAM block. 



File Specification Characteristics 



The CREATE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 



NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 



Wildcarding 

The CREATE operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
CREATE operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 



Extension Sizes 

The CREATE operation returns the size (in blocks) of each allocation 
it makes. If you created only area using FAB fields, the CREATE 
operation writes the size of the allocation in the 2-word ALQ field of 
the FAB. If you created areas using ALL blocks, the CREATE operation 
writes the size of each area allocation in the 2-word ALQ field of the 
ALL block for the area. 



Completion Status and Value 

The CREATE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 

Table 5-5 lists control block fields that are input to the CREATE 
operation. Table 5-6 lists control block fields that are output by 
the CREATE operation. 



Table 5-5: CREATE Input Fields 
Block Field Description 



ALL AID Area number 

ALL ALN Initial area alignment request 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

ALL ALQ Initial area allocation request size (blocks) 
ALL AOP Area option mask 

XB$CTG Contiguous area request 
XB$HRD Area hard location request 

ALL BKZ Area bucket size (blocks) 

ALL DEQ Area default extension size (blocks) 

ALL LOC Initial area location request 

ALL NXT Next XAB address 

DAT NXT Next XAB address 

FAB ALQ Initial file allocation request size (blocks) 

FAB BKS File bucket size (blocks) 

FAB BLS Magtape block size (characters) 

FAB BPA Private buffer pool address 

FAB BPS Private buffer pool size (bytes) 

FAB DEQ Permanent file default extension size (blocks) 

FAB DNA Default string address 

FAB DNS Default string size (bytes) 

FAB FAC Requested access mask 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

FAB FNA File string address 

FAB FNS File string size (bytes) 

FAB FOP File processing option mask 

FB$CTG Contiguous file request 

FB$DFW Defer writing 

FB$DLK No file locking on abnormal close 

FB$F ID Use information in NAM block 

FB$MKD Mark file for deletion 

FB$POS Position magtape after last-closed file 

FB$RWC Rewind magtape after closing file 

FB$RWO Rewind magtape before creating file 

FB$SUP Supersede existing file 

FB$TMD Temporary file, mark for deletion 

FB$TMP Temporary file 



(Continued on next page) 
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Table 5-5 (Cont.)s CREATE Input Fields 



Block Field Description 



FAB FSZ Fixed control area size for VFC records (bytes) 

FAB LCH Logical channel number 

FAB LRL Longest record length 

FAB MRN Maximum record number 

FAB MRS Maximum record size (bytes) 

FAB NAM NAM block address 

FAB ORG File organization code 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 



FAB RAT Record handling mask 



FB$BLK Blocked records 

FB$CR Add CRLF to print record (LF-record-CR) 
FB$FTN FORTRAN-style carriage-control character in 
record 

FB$PRN VFC print record handling 



FAB RFM Record format code 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 



FAB RTV Retrieval pointer count 
FAB SHR Shared access mask 

FB$GET Share find/get access 

FB$NIL No access sharing 

FB$WRI Share find/get/put/update/delete access 

FB$UPI Share any access (user-provided interlock) 

FAB XAB XAB address 

KEY DAN Data area number 

KEY DFL Data bucket fill factor 

KEY DTP Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

KEY FLG Index option mask 

XB$DUP Duplicate record keys allowed 
XB$CHG Record key changes allowed on update 
XB$NUL Null record keys not indexed 

KEY IAN Higher level index area number 

KEY IFL Index bucket fill factor 

KEY KNM Key name buffer address 

KEY LAN Lowest index level area number 

(Continued on next page) 
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Table 5-5 (Cont.)i CREATE Input Fields 



Block 


Field 


Description 


KEY 


NUL 


Null key character 


KEY 


NXT 


Next XAB address 


KEY 


POS 


Key segment positions 


KEY 


REF 


Index reference number 


KEY 


SIZ 


Key segment sizes (bytes) 


NAM 


ESA 


Expanded string buffer address 


NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESS 


Expanded string buffer size (bytes) 


PRO 


NXT 


Next XAB address 


PRO 


PRO 


File protection code 


SUM 


NXT 


Next XAB address 


Table 5-6: CREATE Output Fields 


Block 


Field 


Description 


ALL 


ALQ 


Initial area allocation size (blocks) 


FAB 


ALQ 


Initial file allocation size (blocks) 


FAB 


DEV 


Device characteristic mask 






FB$CCL Carriage-control device 






FB$MDI Multidirectory device 






FB$REC Record-oriented device 






FB$SDI Single-directory device 






FB$SQD Sequential device 






FB$TRM Terminal device 


FAB 


IF I 


Internal file identifier 


FAB 


STS 


Completion status code 


FAB 


STV 


Completion status value 


NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESL 


Expanded string length (bytes) 


NAM 


FID 


File identifier 


NAM 


FNB 


File specification mask 






NB$NOD Node in file string or default string 






NB$DEV Device in file string or default string 






NB$DIR Directory in file string or default string 






NB$QUO Quoted string in file string or default 






string 






NB$NAM File name in file string or default string 






NB$TYP File type in file string or default string 






NB$VER File version in file string or default 






string 






NB$WDI Wildcard directory in file string or 






default string 






NB$WNA Wildcard file name in file string or 






default string 






NB$WTY Wildcard file type in file string or 






default string 






NB$WVE Wildcard file version in file string or 






default string 






NB$WCH Wildcard context established (cleared) 


NAM 


RSL 


Resultant string length (bytes) (cleared) 
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5.4 $DELETE MACRO 

The $DELETE macro calls the DELETE operation routine to remove a 
record from a relative or indexed file. The target of the DELETE 
operation is the current record. The current record must be locked; 
it was automatically locked when the current-record context was set, 
but you must not have unlocked it with a FREE operation. 

If the stream has no current-record context, or if the current record 
is not locked, the DELETE operation returns an error completion. 



FORMAT 

The format for the $DELETE is: 

$DELETE rabaddr [ , [erraddr ] [ , sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the addre;ss of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the DELETE operation. 



OPTIONS 



Internal Stream Identifier 

The DELETE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Fast Deletion (Indexed File) 

If the file is an indexed file, and if its alternate indexes allow 
duplicate keys, then you can speed up the DELETE operation by using 
the fast-deletion procedure. However, this procedure is faster 
because it deletes only those alternate index pointers that it must; 
future retrieval operations may be slowed by the presence of undeleted 
alternate index pointers. 

To use the fast-deletion procedure with the DELETE operation, set the 
RB$FDL mask in the 1-word ROP field of the RAB. If you do not set 
this mask, the DELETE operation does not use the fast-deletion 
procedure . 



Asynchronous Operation 

If you want to execute the DELETE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the DELETE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



5-25 



OPERATION MACRO DESCRIPTIONS 
$DELETE MACRO 



STREAM CONTEXT 

The current-record context after a DELETE operation is undefined; the 
next-record context is unchanged. 



RETURNED VALUES 



Completion Status and Value 

The DELETE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-7 lists control block fields that are input to the DELETE 
operation. Table 5-8 lists control block fields that are output by 
the DELETE operation. 



Table 5-7: DELETE Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 
RB$FDL Fast deletion 


Table 5-8: DELETE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.5 $DISCONNECT MACRO 

The $DISCONNECT macro calls the DISCONNECT operation routine to 
terminate a stream and disconnect it f releasing the internal resources 
it was using. The stream context is lost; you cannot reestablish the 
same stream context by reconnecting the stream with the CONNECT 
operation . 



FORMAT 

The format for the $DISCONNECT is: 

$DISCONNECT rabaddr [ , [erraddr] [ , sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the DISCONNECT operation. 



OPTIONS 



Internal Stream Identifier 

The DISCONNECT operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the DISCONNECT operation asynchronously, set 
the RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the DISCONNECT operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The DISCONNECT operation terminates the stream; therefore there is no 
stream context after the DISCONNECT operation. 



RETURNED VALUES 



Internal Stream Identifier (Cleared) 

The DISCONNECT operation clears the internal stream identifier from 
the 1-word ISI field of the RAB. 



Completion Status and Value 

The DISCONNECT operation returns completion status in the 1-word STS 
field of the RAB and returns a completion value in the 1-word STV 
field of the RAB. Appendix A lists completion status symbols and 
val ues . 
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CHECKLISTS 

Table 5-9 lists control block fields that are input to the DISCONNECT 
operation. Table 5-10 lists control block fields that are output by 
the DISCONNECT operation. 



Table 5-9: DISCONNECT Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-10: DISCONNECT Output Fields 


Block 


Field 


Description 


RAB 
RAB 
RAB 


ISI 
STS 
STV 


Internal stream identifier 
Completion status code 
Completion status value 
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5.6 $DISPLAY MACRO 

The $DISPLAY macro calls the DISPLAY operation routine to write values 
into control block fields. The DISPLAY operation does not alter the 
file in any way. 

When you use the OPEN operation to open a file, you might not know how 
many areas or how many indexes the file has. If, however, you supply 
a SUM block for the OPEN operation, the OPEN operation writes the 
number of areas and number of keys (indexes) in its fields. You can 
then supply ALL blocks and KEY blocks so that the DISPLAY operation 
can fill their fields with values describing the file areas and 
indexes . 



FORMAT 

The format for the $DISPLAY is: 

$DISPLAY fabaddr[, [erraddr] [,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the DISPLAY operation. 

If the file is an indexed file, for each ALL block that you supply, 
the DISPLAY operation fills its fields with values describing the 
corresponding area (if any) of the file. You need not supply an ALL 
block for every area of the file. Note that if the file was opened 
for block access, no information is returned in ALL blocks. 

For each KEY block that you supply, the DISPLAY operation fills its 
fields with values describing the corresponding index (if any) for the 
file. You need not supply a KEY block for every index of the file. 
Note that if the file was opened for block access, no information is 
returned in KEY blocks. 

If you supply a PRO block for a disk file, the DISPLAY operation fills 
its fields with values showing the owner and protection for the file. 

If you supply a DAT block for a disk file, the DISPLAY operation fills 
its fields with values showing the creation date, expiration date, 
revision date, and revision number for the file. 

If you supply a SUM block for a relative or indexed file, the DISPLAY 
operation fills its fields with values showing the number of areas and 
indexes for the file, and with its prologue version number. (If you 
are opening the file for block access, the DISPLAY operation returns 
the number of areas and number of keys as 0, and does not return the 
prologue version number.) 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the DISPLAY 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 
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All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 

of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 

ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



Internal File Identifier 

The DISPLAY operation reads the internal file identifier from the 
1-word IFI field of the FAB. This is the value that was written when 
the file was opened by the CREATE or OPEN operation. 



Key Name Buffer 

If you want the key name string for an index returned to a buffer, 
supply a KEY block for the index; specify the address of a 32-byte 
buffer in the 1-word KNM field of the KEY block. If you do not supply 
a KEY block for an index, or if you specify in its KNM field, the 
DISPLAY operation does not return the key name string. 



STREAM CONTEXT 

The DISPLAY operation does not affect stream context. 



RETURNED VALUES 



Area Descriptions 

For each ALL block that you supply, the DISPLAY operation writes a 
description in its fields of the corresponding area of the file. Area 
is described in the ALL block containing in its AID field; area 1 
is described in the ALL block containing 1 in its AID field; and so 
forth . 

The DISPLAY operation writes three sizes for a file area: the size 
(in blocks) of the unused portion of the area in the 2-word ALQ field 
of the ALL block, the default area extension size (in blocks) in the 
1-word DEQ field of the ALL block, and the area bucket size (in 
blocks) in the 1-byte BKZ field of the ALL block. 

The DISPLAY operation clears the 1-byte AOP field of the ALL block and 
the 1-byte ALN field of the ALL block. 



Key Descriptions 

For each KEY block that you supply, the DISPLAY operation writes a 
description in its fields of the corresponding index of the file. The 
primary index is described in the KEY block containing in its REF 
field; the first alternate index is described in the KEY block 
containing 1 in its REF field; and so forth. 
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The DISPLAY operation writes the key data type code in the 1-byte DTP 
field of the KEY block. The symbols for key data type codes are: 



XB$BN2 16-bit 

XB$BN4 32-bit 

XB$IN2 15-bit 

XB$IN4 31-bit 

XB$PAC Packed 

XB$STG String 



unsigned integer 
unsigned integer 
signed integer 
signed integer 
decimal number 



The DISPLAY operation writes key segment information for the index: 
the number of key segments in the 1-byte NSG field of the KEY block, 
and the total key size (sum of segments, in bytes) in the 1-byte TKS 
field of the KEY block. 



The DISPLAY operation writes the sizes of key segments in the 8-byte 
SIZ field of the KEY block. The size (in bytes) of the first key 
segment is in the first byte of the SIZ field, the size of the second 
segment is in the second byte of the SIZ field, and so forth. If the 
key has fewer than eight segments, the first byte containing 
indicates the number of key segments. 

The DISPLAY operation writes the positions of key segments in the 
8-word POS field of the KEY block. The position (leftmost position is 
0) of the first key segment is in the first word of the POS field, the 
position of the second segment is in the second word of the POS field, 
and so forth. If the key has fewer than eight segments, the remaining 
words of the POS field contain unpredictable values. 

The DISPLAY operation writes a key-characteristics mask in the 1-byte 
FLG field of the KEY block. The symbols for key-characteristics masks 
are : 



XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 



The DISPLAY operation writes the null-key character in the 1-byte NUL 

field of the KEY block. This character is meaningful only if the 

XB$NUL mask in the 1-byte FLG field of the KEY block is set and the 
DISPLAY operation returns the XB$STG code in the 1-byte DTP field of 
the KEY block (indicating a string key) . 

The DISPLAY operation writes area numbers for the index: the area for 

the data level in the 1-byte DAN field of the KEY block, the area for 

the lowest index level in the 1-byte LAN field of the KEY block, and 

the area for higher index levels in the 1-byte IAN field of the KEY 
block . 



The DISPLAY operation writes bucket fill numbers for the index areas: 
the fill number for the data area in the 1-word DFL field of the KEY 
block, and the fill number for the index areas in the 1-word IFL field 
of the KEY block. 



The DISPLAY operation writes bucket sizes for index areas: the data 
area bucket size (in blocks) in the 1-byte DBS field of the KEY block, 
and the index area bucket size (in blocks) in the 1-byte IBS field of 
the KEY block. 



The DISPLAY operation writes virtual block numbers for the index 
areas: the virtual block number for the first data bucket in the 
2-word DVB field of the KEY block, and the virtual block number of the 
root index bucket in the 2-word RVB field of the KEY block. 
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The DISPLAY operation writes the number of levels in the index (not 

including the data level) in the 1-byte LVL field of the KEY block. 

The DISPLAY operation writes the minimum size (in bytes) of a record 

that contains the key for the index in the 1-word MRL field of the KEY 
block . 



File Owner and Protection (Disk File) 

If the file is a disk file, and if you supply a PRO block, the DISPLAY 
operation writes the project (or group) portion of the file owner code 
in the 1-word PRJ field of the PRO block, the programmer (or member) 
portion of the file owner code in the 1-word PRG field of the PRO 
block, and the file protection code in the 1-word PRO field of the PRO 
block . 



File Dates 

If you supply a DAT block for a disk file, the DISPLAY operation 

writes four values in its fields: the creation date in the 4-word CDT 
field of the DAT block, the expiration date in the 4-word EDT field of 

the DAT block, the revision date in the 4-word RDT field of the DAT 

block, and the revision number (number of times the file has been 

wr i te-accessed and then closed) in the 1-word RVN field of the DAT 
block . 



File Summary Information 

If you supply a SUM block, the DISPLAY operation writes three values 
in its fields: the number of file areas in the 1-byte NOA field of 
the SUM block, the number of file indexes in the 1-byte NOK field of 
the SUM block, and the prologue version number (for a relative or 
indexed file) in the 1-word PVN field of the SUM block. 



Completion Status and Value 

The DISPLAY operation returns completion status in the 1-word STS 
field of the FAB and returns a completion value in the 1-word STV 
field of the FAB. Appendix A lists completion status symbols and 
values . 



CHECKLISTS 

Table 5-11 lists control block fields that are input to the DISPLAY 
operation. Table 5-12 lists control block fields that are output by 
the DISPLAY operation. 
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Table 5-11: DISPLAY Input Fields 
Block Field Description 



ALL 


AID 


Area number 


ALL 


NXT 


Next XAB address 


DAT 


NXT 


Next XAB address 


FAB 


IFI 


Internal file identifier 


FAB 


XAB 


XAB address 


KEY 


NXT 


Next XAB address 


KEY 


KNM 


Key name buffer address 


KEY 


REF 


Index reference number 


PRO 


NXT 


Next XAB address 


SUM 


NXT 


Next XAB address 



Table 5-12: DISPLAY Output Fields 
Block Field Description 



ALL ALN Area alignment mask (cleared) 

ALL ALQ Unused area allocation size (blocks) 

ALL AOP Area option mask 

XB$CTG Contiguous area (cleared) 
XB$HRD Hard area location (cleared) 

ALL BKZ Area bucket size (blocks) 

ALL DEQ Area default extension size (blocks) 

DAT CDT File creation date 

DAT EDT File expiration date 

DAT RDT File revision date 

DAT RVN File revision number 

FAB STS Completion status code 

FAB STV Completion status value 

KEY DAN Data area number 

KEY DBS Data area bucket size (blocks) 

KEY DFL Data bucket fill factor 

KEY DTP Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

KEY DVB First data bucket virtual block number 
KEY FLG Index option mask 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 



(Continued on next page) 
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Table 5-12 (Cont.): DISPLAY Output Fields 
Block Field Description 



KEY 


IAN 


Higher level index area number 


KEY 


IBS 


Index area bucket size (blocks) 


KEY 


IFL 


Index bucket fill factor 


KEY 


LAN 


Lowest index level area number 


KEY 


LVL 


Number of index levels (not including data level) 


KEY 


MRL 


Minimum length of record containing key (bytes) 


KEY 


NSG 


Key segment count 


KEY 


NUL 


Null key character 


KEY 


POS 


Key segment positions 


KEY 


RVB 


Root index bucket virtual block number 


KEY 


SIZ 


Key segment sizes (bytes) 


KEY 


TKS 


Total key size (sum of key segment sizes) (bytes) 


PRO 


PRG 


Programmer or member portion of file owner code 


PRO 


PRJ 


Project or group portion of file owner code 


PRO 


PRO 


File protection code 


SUM 


NOA 


Number of areas 


SUM 


NOK 


Number of indexes 


SUM 


PVN 


Prologue version number 
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5.7 $ ENTER MACRO 

The $ENTER macro calls the ENTER operation routine to insert a file 
name into a directory file. 



FORMAT 

The format for the $ENTER is: 

$ENTER f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the ENTER operation. 

You must supply a NAM block for the ENTER operation. 

To supply a NAM block for the ENTER operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the ENTER 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



File Specification 

The ENTER operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 

RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory -- The current directory for the task. 

• Name, type, version — Defaulted to null. 
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The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the ENTER 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
ENTER operation uses no default string. 

If you set the FB$F ID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the ENTER operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the ENTER operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

You must provide a NAM block for the ENTER operation, and must provide 
a valid file identifier in the 3-word FID field of the NAM block. 
This identifier specifies the file for which the entry (name, type, 
and version) will be created in the target directory. 



Expanded String Buffer 

If you want the ENTER operation to return the expanded string for the 
created file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block. 
Specify the size (in bytes) of the expanded string buffer in the 
1-byte ESS field of the NAM block; if you specify in the ESS field, 
the ENTER operation does not return the expanded string. 



Private Buffer Pool 

If you want the ENTER operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the ENTER 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the ENTER operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 
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RETURNED VALUES 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the ENTER operation writes the file 
specification for the target file in this buffer, and writes the 
length (in bytes) of the specification string in the 1-byte ESL field 
of the NAM block. 



Device Characteristics 

The ENTER operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Device and Directory Identifiers 

The ENTER operation returns the device identifier for the target file 
in the 2-word DVI field of the NAM block and the directory identifier 
in the 3-word DID field of the NAM block. 



File Specification Characteristics 



The ENTER operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 



NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 
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Wildcarding 

The ENTER operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block and the 1-byte RSL field of the NAM block; this shows 
that no wildcard context exists and that no resultant string was 
returned . 



Completion Status and Value 

The ENTER operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-13 lists control block fields that are input to the ENTER 
operation. Table 5-14 lists control block fields that are output by 
the ENTER operation. 



Table 5-13: ENTER Input Fields 



Block Field 



Description 



ALL 
DAT 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 
FAB 



NXT 
NXT 
BPA 
BPS 
DNA 
DNS 
FNA 
FNS 
FOP 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

Default string address 

Default string size (bytes) 

File string address 

File string size (bytes) 

File processing option mask 



FB$FID 



Use information in NAM block 



FAB 
FAB 
KEY 
NAM 
NAM 
NAM 
NAM 
NAM 
PRO 
SUM 



LCH 
NAM 
NXT 
DID 
DVI 
ESA 
ESS 
FID 
NXT 
NXT 



Logical channel number 

NAM block address 

Next XAB address 

Directory identifier 

Device identifier 

Expanded string buffer address 

Expanded string buffer size (bytes) 

File identifier 

Next XAB address 

Next XAB address 
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Table 5-14: ENTER Output Fields 



Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FNB File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default string 
Device in file string or default string 
Directory in file string or default string 
Quoted string in file string or default 
str ing 

File name in file string or default string 
File type in file string or default string 
File version in file string or default 
string 

Wildcard directory in file 
default string 

name in file 



string or 



Wildcard file 
default string 
Wildcard file type in 
default string 
Wildcard file version in 
default string 

Wildcard context established 



string 



or 



file string or 
file string or 



(cleared) 



NAM 



RSL 



Resultant string length (bytes) (cleared) 
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5.8 $ ERASE MACRO 

The $ERASE macro calls the ERASE operation routine to erase a file and 
delete its directory entry. Note that erasing a file marks the file 
for deletion, but does not necessarily erase the file immediately; 
the file is erased when it has no accessing programs. The allocation 
for the file is released for use in other files. 



FORMAT 

The format for the $ERASE is: 

$ERASE fabaddr [ , [erraddr] [ , sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the ERASE operation. 

If you supply a NAM block and specify wildcarding, the ERASE operation 
reads the address and length of the expanded string from NAM block 
fields; if you supply a NAM block and specify erase by NAM block, the 
ERASE operation reads NAM block fields to obtain identifiers for the 
target file. 

To supply a NAM block for the ERASE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the ERASE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



File Specification (Nonwildcard ERASE Operation) 

The ERASE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string). 
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RMS-11 defaults are: 

• Device -- The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory -- The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the ERASE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
ERASE operation uses no default string. 

If you set the FB$F ID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the ERASE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the ERASE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

In the same circumstance, the ERASE operation reads the file 
identifier from the 3-word FID field of the NAM block; if this value 
is nonzero, the specified file overrides any directory, name, type, 
and version elements previously obtained, and the file is erased 
without removing any directory entry that may exist for it. 



Erase by Wildcard Specification 

You can use the ERASE operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation and its directory entry are 
deleted, but all fields relevant to wildcard context are preserved 
(for possible subsequent SEARCH operations). 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
ERASE operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section . ) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the ERASE operation erases its contents and deletes its 
directory entry; if not, the ERASE operation does not erase the file 
contents or delete its directory entry, but instead passes control 
block data from the SEARCH operation (in particular, the ER$NMF 
completion status code and the cleared NB$WCH mask in the 1-word FNB 
field of the NAM block) . 
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Expanded String Buffer 

If you erase a file by its file specification, and if you want the 
ERASE operation to return the expanded string for the erased file, 
provide a buffer for the string. Specify the address of the expanded 
string buffer in the 1-word ESA field of the NAM block. Specify the 
size (in bytes) of the expanded string buffer in the 1-byte ESS field 
of the NAM block; if you specify in the ESS field, the ERASE 
operation does not return the expanded string. 



Private Buffer Pool 

If you want the ERASE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
mu ltiple of 4. 

If you specify in either the BPA field or the BPS field, the ERASE 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the ERASE operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
. 



RETURNED VALUES 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block), the ERASE operation writes the expanded 
string for the erased file in the buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 



Device, Directory, and File Identifiers 

If you supply a NAM block, the ERASE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block (unless directory 
processing was bypassed due to use of the file identifier on input) , 
and a file identifier in the 3-word FID field of the NAM block. 



Device Characteristics 

The ERASE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MD I mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 
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• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Wildcard Context 

A nonwildcard ERASE operation clears the NB$WCH mask in the 1-word FNB 
field of the NAM block and the 1-byte RSL field of the NAM block; 
this shows that no wildcarding is in progress and that no resultant 
string was returned. 



File Specification Characteristics 

The ERASE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 



Completion Status and Value 

The ERASE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-15 lists control block fields that are input to the ERASE 
operation. Table 5-16 lists control block fields that are output by 
the ERASE operation. 
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Table 5-15: ERASE Input Fields 
Block Field Description 



A r r 
ALL 


NXT 


Next XAB address 


DAT 


NXT 


Next XAB address 


FAB 


BPA 


Private buffer pool address 


FAB 


BPS 


Private buffer pool size (bytes) 


FAB 


DNA 


Default string address 


FAB 


DNS 


Default string size (bytes) 


FAB 


FNA 


File string address 


FAB 


FNS 


File string size (bytes) 


FAB 


FOP 


File processing option mask 






FB$FID Use information in NAM bio 


FAB 


LCH 


Logical channel number 


FAB 


NAM 


NAM block address 


KEY 


NXT 


Next XAB address 


NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESA 


Expanded string buffer address 


NAM 


ESS 


Expanded string buffer size (bytes) 


NAM 


FID 


File identifier 


NAM 


FNB 


File specification mask 


PRO 


NXT 


Next XAB address 


SUM 


NXT 


Next XAB address 



NB$WCH Wildcard context established 



Table 5-16: ERASE Output Fields 



Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Mul tid irectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 



FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FID File identifier 



(Continued on next page) 
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Table 5-16 (Cont.): ERASE Output Fields 



Block Field Description 



NAM 



FNB 



File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default string 
Device in file string or default string 



string or default 
file string or 



st r ing 
str i ng 



or 
or 



file string or 



Directory in file 
Quoted string in 
str ing 

File name in file 
File type in file 
File version in 
str ing 

Wildcard directory 
default string 
Wildcard file 
default string 
Wildcard file 
default string 
Wildcard file version 
default string 

Wildcard context established 



default 
default 



str ing 
default 

str ing 
s tr i ng 
default 



name 



in file 



in file 



str ing 
str ing 



type in file string 



or 



or 



or 



file string or 



NAM 



RSL 



Resultant string length (bytes) 
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5.9 $ EXTEND MACRO 

The $ EXTEND macro calls the EXTEND operation routine to extend the 
allocation for an open file. 



FORMAT 

The format for the $EXTEND is: 

^EXTEND fabaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the EXTEND operation. 

For each ALL block that you supply, the EXTEND operation extends the 
corresponding area as described in the ALL block. You need not supply 
an ALL block for an area that you do not want to extend, but each 
supplied ALL block must correspond to an area in the file; this means 
that you can supply ALL blocks for areas other than area only for an 
indexed file opened for record access. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the EXTEND 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



Internal File Identifier 

The EXTEND operation reads the internal file identifier from the 
1-word IFI field of the FAB. This is the value written by the CREATE 
or OPEN operation that opened the file. 



Area Extended by FAB 

If you supply no ALL blocks, specify the size (in blocks) of the 
extension in the 2-word ALQ field of the FAB. 

If you want the extension to be contiguous within itself (it will not 
necessarily be contiguous with the file), set the FB$CTG mask in the 
1-word FOP field of the FAB; if you do not set this mask, the 
extension is not necessarily contiguous within itself. 
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Areas Extended by ALL Blocks 

If you supply ALL blocks, the EXTEND operation ignores the ALQ field 
of the FAB, and extends each area specified in an ALL block. Specify 
each area to be extended by supplying an ALL block with the area 
number in the 1-byte AID field of the ALL block. Specify the size of 
the extension (in blocks) for the area in the 2-word ALQ field of the 
ALL block. 

If you want the area extension to be contiguous within itself (it will 
not be contiguous with the previous area extent) , set the XB$CTG mask 
in the 1-byte AOP field of the ALL block. If you do not set this 
mask, the extension will not necessarily be contiguous within itself. 

If you want to place the extension at a specific location, specify an 
alignment mask in the 1-byte ALN field of the ALL block; if you 
specify 0, the EXTEND operation places the extension at any convenient 
location. The symbols for alignment masks are: 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

Specify the number of the logical block or virtual block in the 2-word 
LOC field of the ALL block. 

If you specify logical block alignment, and if you want the extension 
placed only at the location you specify, set the XB$HRD mask in the 
1-byte AOP field of the ALL block. If you do not set this mask, the 
EXTEND operation selects an alternate location if the specified 
location is not available. If you do set this mask, the EXTEND 
operation returns an error completion if the specified location is not 
avai lable . 



STREAM CONTEXT 

The EXTEND operation does not affect stream context. 



RETURNED VALUES 



Extension Sizes 

The EXTEND operation returns the size (in blocks) of each extension it 
makes. If you extended only area using FAB fields, the EXTEND 
operation writes the size of the extension in the 2-word ALQ field of 
the FAB. If you extended areas using ALL blocks, the EXTEND operation 
writes the size of each area extension in the 2-word ALQ field of the 
ALL block for the area. 



Completion Status and Value 

The EXTEND operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-17 lists control block fields that are input to the EXTEND 
operation. Table 5-18 lists control block fields that are output by 
the EXTEND operation. 
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Table 5-17: EXTEND Input Fields 
Block Field Description 



ALL AID Area number 

ALL ALN Area extension alignment request 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

ALL ALQ Area allocation extension request size (blocks) 
ALL AOP Area option mask 

XB$CTG Contiguous area extension request 
XB$HRD Area extension hard location request 

ALL LOC Area extension location request 

ALL NXT Next XAB address 

DAT NXT Next XAB address 

FAB ALQ File allocation extension request size (blocks) 

FAB FOP File processing option mask 

FB$CTG Contiguous file extension request 

FAB IFI Internal file identifier 

FAB XAB XAB address 

KEY NXT Next XAB address 

PRO NXT Next XAB address 

KEY REF Index reference number 

SUM NXT Next XAB address 



Table 5-18: EXTEND Output Fields 
Block Field Description 



ALL ALQ Area allocation extension actual size (blocks) 

FAB ALQ File allocation extension actual size (blocks) 

FAB STS Completion status code 

FAB STV Completion status value 
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5.10 $FIND MACRO (SEQUENTIAL ACCESS) 

The $FIND macro calls the FIND operation routine to transfer a recc 
(or part of a record) from a file to an I/O buffer. The FI. 
operation transfers the entire record if the file is relative c 
indexed, or if it has blocked records; it may transfer only part or 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of a sequential-access FIND operation is the next record 
(for an indexed file, the next record under the current index) . 



FORMAT 

The format for the $FIND is: 

$FIND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 



OPTIONS 



Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Sequential Access 

Specify the RB$SEQ code in the 1-byte RAC field of the RAB. 



STREAM CONTEXT 

The current-record context after a sequential access FIND operation is 
the found record; the next-record context is the record following the 
found record (for an indexed file, the next record under the current 
index) . If the FIND operation returns an error completion, the 
current-record context is undefined, and the next-record context is 
unchanged . 
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RETURNED VALUES 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a sequential-access FIND operation returns the relative 
record number (RRN) for the found record in the 2-word BKT field of 
the RAB. 



RFA 

The FIND operation returns the record file address (RFA) for the found 
record in the 3-word RFA field of the RAB. 



Completion Status and Value 

The FIND operation returns completion 
of the RAB and returns a completion 
the RAB. Appendix A lists completion 



status in the 1-word STS field 
value in the 1-word STV field of 
status symbols and values. 



CHECKLISTS 



Table 5-19 lists control block fields that are input to the FIND 
operation. Table 5-20 lists control block fields that are output by 
the FIND operation. 



Table 5-19: FIND (Sequential Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$SEQ Sequential access 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 



Table 5-20: FIND (Sequential Access) Output Fields 
Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RFA Record file address 

RAB STS Completion status code 

RAB STV Completion status value 
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5.11 $FIND MACRO (KEY ACCESS) 

The $FIND macro calls the FIND operation routine to transfer a record 
(or part of a record) from a sequential disk file (with fixed-length 
records), a relative file, or an indexed file to an I/O buffer. The 
FIND operation transfers the entire record if the file is relative or 
indexed, or if it has blocked records; it may transfer only part of 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of a key-access FIND operation is the record having the 
specified key (under the specified match criterion) . For a relative 
file or for a sequential disk file with fixed-length records, the key 
is a relative record number (RRN) ; for an indexed file, the key is an 
index key under the specified index. 



FORMAT 

The format for the $FIND is: 

$FIND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 



OPTIONS 



Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 



Key of Reference (Indexed File) 

Specify the key of reference in the 1-byte KRF field of the RAB. The 
key of reference is the reference number (REF field of KEY block) for 
the index you want to use for the FIND operation. 
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Key 

Specify a buffer containing the key for the record to be found: 
specify the address of the key buffer in the 1-word KBF field of the 
RAB, and specify the size of the key in the 1-byte KSZ field of the 
RAB. 

For a relative file, or for a sequential file with fixed-length 
records, specify a 4-byte binary relative record number (RRN) as the 
key, and specify the key size as or 4. 

For an indexed file, specify a key of the same type as the key for the 
current index, and specify a key size no greater than the key size for 
the current index. For a nonstring key, the specified key size must 
be the key size defined for the index (or, equivalently , 0); for a 
string key, if you specify a key size smaller than the key size for 
the index, the FIND operation searches for a record whose key begins 
with the specified partial key (under the specified key criterion). 



Key Criterion 

Specify a key-criterion mask in the 1-word ROP field of the RAB. The 
symbols for key-criterion masks are: 

RB$KGE Greater- than-or-equal key criterion 
RB$KGT Greater-than key criterion 

If you specify the key-greater criterion, the FIND operation searches 
for the first record whose key is greater than the key you specify; 
if you specify the key-greater-or-equal criterion, the FIND operation 
searches for the first record whose key is greater than or equal to 
the key you specify; if you specify neither criterion, the FIND 
operation searches for a record whose key exactly matches the key you 
specify. (It is illegal to specify both criteria.) 



STREAM CONTEXT 

The current-record context after a key access FIND operation is the 
found record; the next-record context is unchanged. If the FIND 
operation returns an error completion, the current-record context is 
undefined, and the next-record context is unchanged. 



RETURNED VALUES 



RFA 

The FIND operation returns the record file address (RFA) for the found 
record in the 3-word RFA field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, the FIND operation returns the RRN of the found record in the 
2-word BKT field of the RAB. 
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Completion Status and Value 



The FIND operation returns completion 
of the RAB and returns a completion 
the RAB. Appendix A lists completion 



status in the 1-word STS field 
value in the 1-word STV field of 
status symbols and values. 



CHECKLISTS 



Table 5-21 lists control block fields that are input to the FIND 
operation. Table 5-22 lists control block fields that are output by 
the FIND operation. 



Table 5-21: FIND (Key Access) Input Fields 
Block Field Description 



RAB 


ISI 


Internal stream identifier 


RAB 


KBF 


Key buffer address 


RAB 


KRF 


Key of reference 


RAB 


KSZ 


Key size (bytes) 


RAB 


RAC 


Record access code 



RB$KEY Key access 
RAB ROP Record processing option mask 



RB$ASY Asynchronous operation 

RB$KGE Greater- than-or-equal key criterion 

RB$KGT Greater-than key criterion 



Table 5-22: FIND (Key Access) Output Fields 
Block Field Description 



RAB BKT Relative record number (RRN) 

RAB RFA Record file address 

RAB STS Completion status code 

RAB STV Completion status value 
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5.12 $FIND MACRO (RFA ACCESS) 

The $FIND macro calls the FIND operation routine to transfer a record 
(or part of a record) from a file to an I/O buffer. The FIND 
operation transfers the entire file if the file is relative or 
indexed, or if it has blocked records; it may transfer only part of 
the record if the record spans block boundaries. The FIND operation 
does not transfer the record to a user buffer. 

The target of an RFA-access FIND operation is the record having the 
record file address (RFA) you specify. 



FORMAT 

The format for the $F IND is: 

$F I ND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FIND operation. 



OPTIONS 



Internal Stream Identifier 

The FIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the FIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



RFA Access 

Specify the RB$RFA code in the 1-byte RAC field of the RAB. 



RFA 

Specify the RFA for the record to be found in the 3-word RFA field of 
the RAB. 



STREAM CONTEXT 

The current-record context after an RFA access FIND operation is the 
found record (for an indexed file, in the context of the primary 
index); the next-record context is unchanged. If the FIND operation 
returns an error completion, the current-record context is undefined, 
and the next-record context is unchanged. 
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RETURNED VALUES 



RRN 

For a relative file or for a sequential disk file with fixed-length 

records, the FIND operation returns the RRN of the found record in the 
2-word BKT field of the RAB. 



Completion Status and Value 

The FIND operation returns completion status in the 1-word STS field 

of the RAB and returns a completion value in the 1-word STV field of 

the RAB.. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-23 lists control block fields that are input to the FIND 
operation. Table 5-24 lists control block fields that are output by 
the FIND operation. 



Table 5-23: FIND (RFA Access) Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
RAC 


Internal stream identifier 
Record access code 

RB$RFA RFA access 


RAB 
RAB 


RFA 
ROP 


Record file address 

Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-24: FIND (RFA Access) Output Fields 


Block 


Field 


Description 


RAB 
RAB 
RAB 


BKT 
STS 
STV 


Relative record number (RRN) 
Completion status code 
Completion status value 
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5.13 $FLUSH MACRO 

The $FLUSH macro calls the FLUSH operation routine to write any 
unwritten buffers for a stream. The FLUSH operation does not affect 
stream context, except that the current-record context is undefined 
for a following TRUNCATE or UPDATE operation. 

Note one special case: if a file was opened for deferred writing 
(FB$DFW set in the FOP field of the FAB for the CREATE or OPEN 
operation) , and was not opened for write sharing (FB$WRI cleared in 
the SH# field of the FAB) , then a buffer may be controlled by a 
different stream, and it will not be written by the FLUSH operation. 



FORMAT 

The format for the $FLUSH is: 

$FLUSH rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FLUSH operation. 



OPTIONS 



Internal Stream Identifier 

The FLUSH operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the FLUSH operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FLUSH operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The FLUSH operation does not affect stream context, except that the 
current-record context is undefined for a following TRUNCATE or UPDATE 
operation . 



RETURNED VALUES 



Completion Status and Value 

The FLUSH operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 

Table 5-25 lists control block fields that are input to the FLUSH 
operation. Table 5-26 lists control block fields that are output by 
the FLUSH operation. 

Table 5-25: FLUSH Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-26: FLUSH Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.14 $FREE MACRO 

The $FREE macro calls the FREE operation routine to free a locked 
bucket for a stream. The FREE operation does not affect stream 
context, except that the current-record context is undefined for a 
following DELETE, TRUNCATE, or UPDATE operation. 



FORMAT 

The format for the $FREE is: 

$FREE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the FREE operation. 



OPTIONS 



Internal Stream Identifier 

The FREE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the FREE operation asynchronously, set the 
RB$ AS Y mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the FREE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The FREE operation does not affect stream context, except that the 
current-record context is undefined for a following DELETE, TRUNCATE, 
or UPDATE operation. 



RETURNED VALUES 



Completion Status and Value 

The FREE operation returns completion status in the 1-word STS field 

of the RAB and returns a completion value in the 1-word STV field of 

the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-27 lists control block fields that are input to the FREE 
operation. Table 5-28 lists control block fields that are output by 
the FREE operation. 



5-58 



OPERATION MACRO DESCRIPTIONS 
$FREE MACRO 



Table 5-27: FREE Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-28: FREE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.15 $GET MACRO (SEQUENTIAL ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a file to an I/O buffer and to a user buffer. 

The target of a sequential-access GET operation depends on whether the 
previous operation was a FIND operation: 

• If the previous operation was a successful FIND operation, the 
target of a sequential-access GET operation is the current 
record (or the first following record if the current record 
was deleted or its key changed in the interim) . 

• If the previous operation was not a successful FIND operation, 
the target of a sequential-access GET operation is the next 
record (for an indexed file, the next record under the current 
index) . 



FORMAT 

The format for the $GET is: 

$GET rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the GET operation. 



OPTIONS 



Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Sequential Access 

Specify the RB $ S E Q code in the 1-byte RAC field of the RAB. 



User Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode); the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 
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Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 



Locate Mode 

If you want the GET operation to use locate mode (in which the record 
may not be transferred to the user buffer) , set the RB$LOC mask in the 
1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 



STREAM CONTEXT 

The current-record context after a sequential access GET operation is 
the retrieved record; the next-record context is the record following 
the retrieved record. 

If the GET operation returns an error completion, the current-record 
context is undefined, and the next-record context is unchanged. 



RETURNED VALUES 



Record 

The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB, and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field; if you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a sequential-access GET operation returns the relative record 
number (RRN) for the retrieved record in the 2-word BKT field of the 
RAB. 



RFA 

The GET operation returns the record file address (RFA) for the 
retrieved record in the 3-word RFA field of the RAB. 
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Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-29 lists control block fields that are input to the GET 
operation. Table 5-30 lists control block fields that are output by 
the GET operation. 



Table 5-29: GET (Sequential Access) Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$SEQ Sequential access 

RAB RHB VFC control buffer address 
RAB ROP Record processing option mask 

RB$AS Y Asynchronous operation 
RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-30: GET (Sequential Access) Output Fields 
Block Field Description 



RAB 


BKT 


Relative record number (RRN) 


RAB 


RBF 


Record buffer address 


RAB 


RFA 


Record file address 


RAB 


RSZ 


Record size (bytes) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.16 $GET MACRO (KEY ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a sequential disk file (with fixed-length records) , a relative 
file, or an indexed file to an I/O buffer and to a user buffer. 

The target of a key-access GET operation is the record having the 
specified key (under the specified match criterion). For a relative 
file or for a sequential disk file with fixed-length records, the key 
is a relative record number (RRN) ; for an indexed file, the key is an 
index key under the specified index. 



FORMAT 

The format for the $GET is: 

$GET rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the GET operation. 



OPTIONS 



Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 



Key of Reference (Indexed File) 

Specify the key of reference in the 1-byte KRF field of the RAB. The 
key of reference is the reference number (REF field of KEY block) for 
the index you want to use for the GET operation. 



Key 

Specify a buffer containing the key for the record to be retrieved: 
specify the address of the key buffer in the 1-word KBF field of the 
RAB, and specify the size of the key in the 1-byte KSZ field of the 
RAB. 
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For a relative file or for a sequential file with fixed-length 
records, specify a 4-byte binary relative record number (RRN) as the 
key, and specify the key size as or 4. 

For an indexed file, specify a key of the same type as the key for the 
current index, and specify a key size no greater than the key size for 
the current index. For a nonstring key, the specified key size must 
be the key size defined for the index (or, equi valently , 0); for a 
string key, if you specify a key size smaller than the key size for 
the index, the GET operation searches for a record whose key begins 
with the specified partial key (under the specified key criterion) . 



Key Criterion 

Specify a key-criterion mask in the 1-word ROP field of the RAB . The 
symbols for key-criterion masks are: 

RB$KGE Greater- than-or-equal key criterion 
RB$KGT Greater-than key criterion 

If you specify the key-greater criterion, the GET operation searches 
for the first record whose key is greater than the key you specify; 
if you specify the key-greater-or-equal criterion, the GET operation 
searches for the first record whose key is greater than or equal to 
the key you specify; if you specify neither criterion, the GET 
operation searches for a record whose key exactly matches the key you 
speci f y . 



User Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode); the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 



Locate Mode 

If you want the GET operation to use locate mode (in which the record 
may not be transferred to the user buffer) , set the RB$LOC mask in the 
1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 



STREAM CONTEXT 

The current-record context after a key access GET operation is the 
retrieved record; the next-record context is the record following the 
retrieved record. 

If the GET operation returns an error completion, the current-record 
context is undefined, and the next-record context is unchanged. 
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RETURNED VALUES 



Record 

The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB , and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field,. If you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a key-access GET operation returns the relative record number 
(RRN) for the retrieved record in the 2-word BKT field of the RAB. 



RFA 

The GET operation returns the record file address (RFA) for the 
retrieved record in the 3-word RFA field of the RAB. 



Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-31 lists control block fields that are input to the GET 
operation. Table 5-32 lists control block fields that are output by 
the GET operation. 
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Table 5-31: GET (Key Access) Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 

RAB KBF Key buffer address 

RAB KRF Key of reference 

RAB KSZ Key size (bytes) 

RAB RAC Record access code 

RB$KEY Key access 

RAB RHB VFC control buffer address 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$KGE Greater- than-or-equal key criterion 

RB$KGT Greater-than key criterion 

RB$LOC Locate mode 



RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-32: GET (Key Access) Output Fields 
Block Field Description 



RAB 


BKT 


Relative record number (RRN) 


RAB 


RBF 


Record buffer address 


RAB 


RFA 


Record file address 


RAB 


RSZ 


Record size (bytes) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.17 $GET MACRO (RFA ACCESS) 

The $GET macro calls the GET operation routine to transfer a record 
from a file to an I/O buffer and to a user buffer. 

The target of an RFA-access GET operation is the record having the 
record file address (RFA) you specify. 



FORMAT 

The format for the $GET is: 

$GET rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the GET operation. 



OPTIONS 



Internal Stream Identifier 

The GET operation reads the internal stream identifier from the 1-word 
ISI field of the RAB . 



Asynchronous Operation 

If you want to execute the GET operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the GET operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



RFA Access 

Specify the RB$RFA code in the 1-byte RAC field of the RAB. 



RFA 

Specify the RFA for the record to be retrieved in the 3-word RFA field 
of the RAB. 



User Buffer 

Specify a user buffer for the GET operation. The GET operation copies 
the retrieved record to this buffer if you do not specify locate mode 
(see next section, Locate Mode); the GET operation may copy the 
retrieved record to this buffer even if you specify locate mode. 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 
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If the file is in VFC record format, specify the address of a buffer 
for the fixed-length portion of the record in the 1-word RHB field of 
the RAB. 



Locate Mode 

If you want the GET operation to use locate mode (in which the record 
may not be transferred to the user buffer) , set the RB$LOC mask in the 
1-word ROP field of the RAB; if you do not set this mask, the record 
is transferred to the user buffer. 



STREAM CONTEXT 

The current-record context after an RFA access GET operation is the 
retrieved record (for an indexed file, in the context of the primary 
index) ; the next-record context is the record following the retrieved 
record. If the GET operation returns an error completion, the 
current-record context is undefined, and the next-record context is 
unchanged . 



RETURNED VALUES 



Record 

The GET operation returns the address and size of the retrieved record 
in the 1-word RBF field of the RAB, and the size (in bytes) of the 
record in the 1-word RSZ field of the RAB. 

If you did not specify locate mode for the GET operation, the record 
address returned in the RBF field is the address you specified in the 
UBF field. If you specified locate mode, the record address returned 
in the RBF field is either the address you specified in the UBF field, 
or the address of a location in an I/O buffer. 

If the file is in VFC format, the GET operation writes the 
fixed-length portion of the record in the buffer you specified in the 
RHB field of the RAB. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, an RFA-access GET operation returns the relative record 
number (RRN) for the retrieved record in the 2-word BKT field of the 
RAB. 



Completion Status and Value 

The GET operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-33 lists control block fields that are input to the GET 
operation. Table 5-34 lists control block fields that are output by 
the GET operation. 
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Table 5-33: GET (RFA Access) Input Fields 



Block Field Description 



RAB ISI Internal stream identifier 
RAB RAC Record access code 

RB$RFA RFA access 

RAB RFA Record file address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 
RB$LOC Locate mode 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-34: GET (RFA Access) Output Fields 



Block Field Description 



RAB 


BKT 


Relative record number (RRN) 


RAB 


RBF 


Record buffer address 


RAB 


RSZ 


Record size (bytes) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.18 $NXTVOL MACRO 

The $NXTVOL macro calls the NXTVOL operation routine to advance the 
context for a stream to the beginning of the next magtape volume. 



FORMAT 

The format for the $NXTVOL is: 

$NXTVOL rabaddr [ , [erraddr] [ , sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the NXTVOL operation. 



OPTIONS 



Internal Stream Identifier 

The NXTVOL operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the NXTVOL operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the NXTVOL operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The NXTVOL operation destroys the current-record context; the 
next-record context after the NXTVOL operation is the first record of 
the new volume (or end-of-file, if there are no records on the new 
volume) . 



RETURNED VALUES 



Completion Status and Value 

The NXTVOL operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-35 lists control block fields that are input to the NXTVOL 
operation. Table 5-36 lists control block fields that are output by 
the NXTVOL operation. 
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Table 5-35: NXTVOL Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-36: NXTVOL Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.19 $OPEN MACRO 

The $OPEN macro calls the OPEN operation routine to open a file for 
processing by the calling task. 



FORMAT 

The format for the $OPEN is: 

$OPEN f abaddr [ , [erraddr] [ , sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the OPEN operation. 

If you supply a NAM block and specify open by NAM block, the OPEN 
operation reads NAM block fields to obtain identifiers for the target 
file. 

To supply a NAM block for the OPEN operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

For each ALL block that you supply, the OPEN operation fills its 
fields with values describing the corresponding area (if any) of the 
file. You need not supply an ALL block for every area of the file. 
(If you are opening the file for block access, the OPEN operation 
writes information describing the file as a whole in the all block for 
area . ) 

For each KEY block that you supply, the OPEN operation fills its 
fields with values describing the corresponding index (if any) for the 
file. You need not supply a KEY block for every index of the file. 
(If you are opening the file for block access, the OPEN operation does 
not write in KEY blocks.) 

If you supply a PRO block for a disk file, the OPEN operation fills 
its fields with values showing the owner and protection for the file. 

If you supply a DAT block for a disk file, the OPEN operation fills 
its fields with values showing the creation date, expiration date, 
revision date, and revision number for the file. 

If you supply a SUM block for a relative or indexed file, the OPEN 
operation fills its fields with values showing the number of areas and 
indexes for the file, and with its prologue version number. (If you 
are opening the file for block access, the OPEN operation returns the 
number of areas and number of keys as 0, and does not return the 
prologue version number.) 

This information is especially useful if you do not know how many 
areas or keys an indexed file has when you open it. If you supply a 
SUM block for the OPEN operation, you can get the number of areas and 
number of indexes from its fields, and then supply the correct number 
of ALL blocks and KEY blocks for the DISPLAY operation. 
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To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the OPEN 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecut i ve . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



File Specification (Nonwildcard OPEN Operation) 

The OPEN operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string) , and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string). 

RMS-11 defaults are: 

• Device -- The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the OPEN 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
OPEN operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the OPEN operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the OPEN operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 

In the same circumstance, the OPEN operation reads the file identifier 
from the 3-word FID field of the NAM block; if this value is zero, 
the specified file overrides any directory, name, type, and version 
elements previously obtained. 
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Open with Wildcard Context 

If you want to open a file that was found by a wildcard SEARCH 
operation (using the FAB and NAM block that the SEARCH operation 
used) , set the FB$F ID mask in the 1-word FOP field of the FAB; this 
causes the OPEN operation to open the file without altering wildcard 
context . 



Expanded String Buffer 

If you want the OPEN operation to return the expanded string for the 
opened file, provide a buffer for the string. Specify the address of 
the expanded string buffer in the 1-word ESA field of the NAM block 
and its size (in bytes) in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the OPEN operation does not return the 
expanded string. 



Key Name Buffer 

If you want the key name string for an index returned to a buffer, 
supply a KEY block for the index. Specify the index reference number 
in the 1-byte REF field of the KEY block, and specify the address of a 
32-byte buffer in the 1-word KNM field of the KEY block. If you do 
not supply a KEY block for an index, or if you specify in its KNM 
field, the OPEN operation does not return the key name string. 



While-Open Default Extension Sizes 

If you want to override the default extension size for the file while 
it is open, specify the while-open default file extension size (in 
blocks) in the 1-word DEQ field of the FAB. If you specify 0, the 
OPEN operation does not establish a while-open default extension size 
for the file; instead, it uses the permanent default extension size. 

The while-open default extension size for a file remains in force 
while the file is open, but does not change the file extension size 
established when the file was created. 



Private Buffer Pool 

If you want the OPEN operation to use a private buffer pool instead of 
the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the OPEN 
operation uses the central buffer pool. 

The pool that the OPEN operation uses is also used by the DISPLAY and 
EXTEND operations, and by stream and record or block operations while 
the file is open. 



Logical Channel 

Specify the logical channel for the OPEN operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 
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The logical channel that the OPEN operation uses is also used by the 
DISPLAY and EXTEND operations, and by stream and record or block 
operations while the file is open. 



Retrieval Pointers 

Specify the number of retrieval pointers for the open file in the 
1-byte RTV field of the FAB. If you specify 0, the OPEN operation 
uses the operating system default; if you specify -1, the OPEN 
operation maps as much of the file as possible. 



Requested -Access 

Specify one or more requested-access masks in the 1-byte FAC field of 
the FAB. This mask determines the access that the opening program has 
while the file is open. If you specify no requested-access mask, 
find/get access is allowed (the OPEN operation uses the mask FB$GET) . 
The symbols for requested-access masks are: 



FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 



Note that FB$REA and FB$WRT override any record access requested. 



Access Sharing 

Specify the kinds of access that your program will share with other 
programs by setting an access-sharing mask in the 1-byte SHR field of 
the FAB. The symbols for access-sharing masks are: 

FB$GET Share find/get access 

FB$N I L No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 

The kinds of access sharing are: 

• Shared read access 

Your program is willing to allow other programs to read the 
file, but not to write it. 

• Shared write access 

Your program is willing to allow other programs to both read 
and write the file. Shared write access is not allowed for a 
sequential file unless the file has undefined record format 
and your program opens the file for block access; shared 
write access is also not allowed for a relative or indexed 
file that your program opens for block access. In such cases, 
RMS-11 automatically converts the shared write access 
specification to a shared read access specification 
internally. 
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• No shared access 

Your program is not willing to allow other programs to either 
read or write the file. RMS-11 does, however, allow other 
programs to read the file unless your program also requests 
some form of write access. 

• User-provided interlocking 

Your program and other cooperating programs define and enforce 
their own access interlocking; RMS-11 does not check access 
sharing. User-provided interlocking is allowed only for 
sequential disk files; otherwise, the FB$UPI mask is ignored 
(but other masks are honored) . 



Deferred Writing 

If you want deferred buffer writing for the open file, set the FB$DFW 
mask in the 1-word FOP field of the FAB; This means that RMS-11 does 
not necessarily write its buffers during a write-type operation 
(DELETE, PUT, or UPDATE) , but instead writes buffers only when it 
needs them for other operations (or when your program executes the 
FLUSH operation for the stream) . 

If you do not set the FB$DFW mask, the DELETE, PUT, and UPDATE 
operations write buffers to the file immediately. 

Note that record operations always use a form of deferred buffer 
writing for sequential files, and that block operations never use 
deferred buffer writing. Therefore you need only decide whether to 
use deferred writing for a record stream to a relative or indexed 
file. 



File Locking 

If you want the file to remain unlocked even if it is closed 
abnormally, set the FB$DLK mask in the 1-word FOP field of the FAB; 
if you do not set this mask, the operating system locks the file if it 
is closed abnormally. 



Magtape Beginning-of-Fi le Positioning 

If you have requested some form of write access, and if you want a 

magtape file positioned to the beginning of the file when it is 

opened, set the FB$NEF mask in the 1-word FOP field of the FAB; if 
you do not set this mask, and if you requested some form of write 

access, the magtape is positioned to the end-of-file when the file is 
opened . 



Rewinding Magtape Before Open 

If you want a magtape rewound before a magtape file is opened, set the 
FB$RWO mask in the 1-word FOP field of the FAB; if you do not set 
this mask, the OPEN operation searches only from the current magtape 
position to the end of the magtape. 
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Rewinding Magtape on Close 

If you want the magtape rewound when the opened file is closed, set 

the FB$RWC mask in the 1-word FOP field of the FAB. If you do not set 

this mask, the magtape will not be rewound on close unless you set the 

FB$RWC mask for the CLOSE operation. Note, however, that if you set 
the FB$RWC mask for the OPEN operation, the magtape will be rewound 
even if you do not set the FB$RWC mask for the CLOSE operation. 



RETURNED VALUES 



Internal File Identifier 

The OPEN operation writes an internal file identifier in the 1-word 
IFI field of the FAB. (The CLOSE operation clears the internal file 
ident i f ier . ) 

The CLOSE,, CONNECT, DISPLAY, and EXTEND operations read the internal 
file identifier; do not alter the IFI field while the file is open. 



Device Characteristics 

The OPEN operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Device, Directory, and File Identifiers 

If you supply a NAM block, the OPEN operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block (unless directory 
processing was bypassed due to use of the file identifier on input), 
and a file identifier in the 3-word FID field of the NAM block. 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the OPEN operation writes the expanded 
string for the opened file in this buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 
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File Allocation, Bucket Size, and Contiguity 

The OPEN operation writes the file allocation size (in blocks) in the 
2-word ALQ field of the FAB, and the file bucket size or largest area 
bucket size (in blocks) in the 1-byte BKS field of the FAB. If the 
file is contiguous, the OPEN operation sets the FB$CTG mask in the 
1-word FOP field of the FAB. 



Extension size 

The OPEN operation writes the current default extension size for the 
open file in the 1-word DEQ field of the FAB. 



File Organization 

The OPEN operation writes the file organization code in the 1-byte ORG 
field of the FAB. The symbols for file organization codes are: 

FB$IDX Indexed file organization 
FB$REL Relative file organization 
FB$SEQ Sequential file organization 



Record Format 



The OPEN operation writes the record format code in the 1-byte RFM 
field of the FAB. The symbols for record format codes are: 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 



If the record format is VFC, the OPEN operation writes the size (in 
bytes) of the VFC header field in the 1-byte FSZ field of the FAB; 
otherwise it writes in the FSZ field. 



Blocked Records (Sequential Disk File) 

If the file was created specifying blocked records, the OPEN operation 
sets the FB$BLK mask in the 1-byte RAT field of the FAB. (The OPEN 
operation sets the mask if it was set when the file was created, even 
if the file is not a sequential file; preservation of this mask 
allows you to copy a sequential file to a file of a different 
organization and back without losing the blocked-record 
characteristic.) 



Record-Output Handling 

The OPEN operation writes the record-output mask in the 1-byte RAT 
field of the FAB. The symbols for record-output masks are: 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 
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Record Size 

The OPEN operation writes the maximum permitted record size (in bytes) 
in the 1-word MRS field of the FAB. 



Maximum Record Number 

If the file is a relative file (FB$REL in the ORG field), the OPEN 
operation writes the maximum record number in the 2-word MRN field of 
the FAB (unless you are opening the file for block access) . 



Magtape Block Size 

For a magtape file, the OPEN operation writes the block size (in 
characters) in the 1-word BLS field of the FAB. 



Longest Record Length 

The OPEN operation writes the length of the longest record in the file 
in the 1-word LRL field of the FAB; this value is meaningful only for 
sequential files. 



Area Descriptions 

For each ALL block that you supply, the OPEN operation writes a 
description in its fields of the corresponding area of the file 
(unless you are opening the file for block access). Area is 
described in the ALL block containing in its AID field, area 1 is 
described in the ALL block containing 1 in its AID field, and so 
forth . 

The OPEN operation writes three sizes for a file area: the size (in 
blocks) of the unused portion of the area in the 2-word ALQ field of 
the ALL block, the default area extension size (in blocks) in the 
1-word DEQ field of the ALL block, and the area bucket size (in 
blocks) in the 1-byte BKZ field of the ALL block. (If you are opening 
the file for block access, only the ALL block for area is written, 
and the ALL block contains the current file allocation size, default 
file extension size, and file bucket size.) 

The OPEN operation clears the 1-byte ALN field of the ALL block and 
the XB$HRD mask in the 1-byte AOP field of the ALL block. If you are 
opening a sequential or relative file for any access, or an indexed 
file for block access, the OPEN operation sets the XB$CTG mask in the 
1-byte AOP field of the ALL block if the file is contiguous; 
otherwise it clears the entire 1-byte AOP field of the ALL block. 



Key Descriptions 

For each KEY block that you supply, the OPEN operation writes a 

description in its fields of the corresponding index of the file. 

(The OPEN operation does not write in KEY blocks if you are opening 
the file for block access.) 

The primary index is described in the KEY block containing in its 
REF field, the first alternate index is described in the KEY block 

containing 1 in its REF field, and so forth. 
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The OPEN operation writes the key data type code in the 1-byte DTP 
field of the KEY block. The symbols for key data type codes are: 



XB$BN2 16-bit 

XB$BN4 32-bit 

XB$IN2 15-bit 

XB$IN4 31-bit 

XB$PAC Packed 

XB$STG String 



unsigned integer 
unsigned integer 
signed integer 
signed integer 
decimal number 



The OPEN operation writes the sizes of key segments in the 8-byte SIZ 
field of the KEY block. The size (in bytes) of the first key segment 
is in the first byte of the SIZ field, the size of the second segment 
is in the second byte of the SIZ field, and so forth. If the key has 
fewer than eight segments, the first byte containing establishes the 
number of key segments. 

The OPEN operation writes the positions of key segments in the 8-word 
POS field of the KEY block. The position (leftmost position is 0) of 
the first key segment is in the first word of the POS field, the 
position of the second segment is in the second word of the POS field, 
and so forth. If the key has fewer than eight segments, the remaining 
words of the POS field contain unpredictable values. 

The OPEN operation writes a key flags mask in the 1-byte FLG field of 
the KEY block. The symbols for key flags masks are: 



XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 



The OPEN operation writes the null-key character in the 1-byte NUL 
field of the KEY block; this character is meaningful only if the 
XB$NUL mask in the FLG field is set and if the key is a string key 
(XB$STG in the DTP field) . 

The OPEN operation writes area numbers for the index: the area for 
the data level in the 1-byte DAN field of the KEY block, the area for 
the lowest index level in the 1-byte LAN field of the KEY block, and 
the area for higher index levels in the 1-byte IAN field of the KEY 
block . 



The OPEN operation writes bucket fill numbers for the index areas: 
the fill number for the data area in the 1-word DFL field of the KEY 
block, and the fill number for the index areas in the 1-word IFL field 
of the KEY block. 



The OPEN operation writes bucket sizes for index areas: the data area 

bucket size (in blocks) in the 1-byte DBS field of the KEY block, and 

the index area bucket size (in blocks) in the 1-byte IBS field of the 
KEY block. 



The OPEN operation writes virtual block numbers for the index areas: 

the virtual block number for the first data bucket in the 2-word DVB 

field of the KEY block, and the virtual block number of the root index 
bucket in the 2-word RVB field of the KEY block. 



The OPEN operation writes the number of levels in the index (not 
including the data level) in the 1-byte LVL field of the KEY block. 

The OPEN operation writes the minimum size (in bytes) of a record that 
contains the key for the index in the 1-word MRL field of the KEY 
block . 
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The OPEN operation writes key segment information for the index: the 
number of key segments in the 1-byte NSG field of the KEY block, and 
the total key size (sum of segments, in bytes) in the 1-byte TKS field 
of the KEY block. 



File Owner and Protection (Disk File) 

If the file is a disk file, and if you supply a PRO block, the OPEN 
operation writes the project (or group) portion of the file owner code 
in the 1-word PRJ field of the PRO block, the programmer (or member) 
portion of the file owner code in the 1-word PRG field of the PRO 
block, and the file protection code in the 1-word PRO field of the PRO 
block . 



File Dates 

If you supply a DAT block for a disk file, the OPEN operation writes 
four values in its fields: the creation date in the 4-word CDT field 
of the DAT block, the expiration date in the 4-word EDT field of the 
DAT block, the revision date in the 4-word RDT field of the DAT block, 
and the revision number (number of times the file has been opened for 
write access and then closed) in the 1-word RVN field of the DAT 
block . 



File Summary Information 

If you supply a SUM block and are opening an indexed file, the OPEN 
operation writes three values in its fields: the number of file areas 
in the 1-byte NOA field of the SUM block, the number of file indexes 
in the 1-byte NOK field of the SUM block, and the prologue version 
number (for a relative or indexed file) in the 1-word PVN field of the 
SUM block. (If you are opening the file for block access, the OPEN 
operation returns the number of areas and the number of keys as 0, and 
does not return the prologue version number.) 



File Specification Characteristics 

The OPEN operation sets masks in the 1-word FNB field of the NAM block 
to show which file specification elements were present in the file 
string and default string. These masks and their meanings are: 

NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 



Wildcard Context Information 

If you cleared the FB$FID mask, the OPEN operation clears the NB$WCH 
mask in the 1-word FNB field of the NAM block and the 1-byte RSL field 
of the NAM block; this shows that no wildcard context information 
exists after the operation and that no resultant string was returned. 
If you set the FB$FID mask, the OPEN operation does not alter the 
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NB$WCH mask, and (if the NB$WCH mask is set) does not alter the RSL 
field. 



Completion Status and Value 

The OPEN operation returns completion status in the 1-word STS field 

of the FAB and returns a completion value in the 1-word STV field of 

the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-37 lists control block fields that are input to the OPEN 
operation. Table 5-38 lists control block fields that are output by 
the OPEN operation. 



Table 5-37: OPEN Input Fields 
Block Field Description 



ALL AID Area number 

ALL NXT Next XAB address 

DAT NXT Next XAB address 

FAB BPA Private buffer pool address 

FAB BPS Private buffer pool size (bytes) 

FAB DEQ While-open file default extension size (blocks) 

FAB DNA Default string address 

FAB DNS Default string size (bytes) 

FAB FAC Requested access mask 

FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

FAB FNA File string address 

FAB FNS File string size (bytes) 

FAB FOP File processing option mask 

FB$DFW Defer writing 

FB$DLK No file locking on abnormal close 

FB$FID Use information in NAM block 

FB$NEF No end-of-file magtape positioning 

FB$RWC Rewind magtape after closing file 

FB$RWO Rewind magtape before searching for file 

FAB LCH Logical channel number 

FAB NAM NAM block address 

FAB RTV Retrieval pointer count 

FAB SHR Shared access mask 

FB$GET Share find/get access 

FB$NIL No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 



(Continued on next page) 
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Table 5-37 (Cont.): OPEN Input Fields 
Block Field Description 



FAB XAB XAB address 

KEY KNM Key name buffer address 

KEY NXT Next XAB address 

KEY REF Index reference number 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESA Expanded string buffer address 

NAM ESS Expanded string buffer size (bytes) 

NAM FID File identifier 

NAM FNB File specification mask 

NB$WCH Wildcard context established 

PRO NXT Next XAB address 

SUM NXT Next XAB address 



Table 5-38: OPEN Output Fields 
Block Field Description 



ALL 
ALL 
ALL 



ALL 
ALL 
DAT 
DAT 
DAT 
DAT 
FAB 
FAB 
FAB 
FAB 
FAB 



ALN 
ALQ 
AOP 



BKZ 
DEQ 
CDT 
EDT 
RDT 
RVN 
ALQ 
BKS 
BLS 
DEQ 
DEV 



Area alignment mask 

Unused area allocation size (blocks) 
Area option mask 

XB$CTG Contiguous area 

XB$HRD Hard area location (cleared) 

Area bucket size (blocks) 

Area default extension size (blocks) 

File creation date 

File expiration date 

File revision date 

File revision number 

Current file allocation (blocks) 

File bucket size (blocks) 

Magtape block size (characters) 

Current file default extension size (blocks) 

Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 



FAB 



FAB 
FAB 
FAB 



FOP 



FSZ 
IFI 
LRL 



File processing option mask 
FB$CTG Contiguous file 

Fixed control area size for VFC records (bytes) 
Internal file identifier 
Longest record length 



(Continued on next page) 
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Table 5-38 (Cont.): OPEN Output Fields 
Block Field Description 



FAB MRN Maximum record number 

FAB MRS Maximum record size (bytes) 

FAB ORG File organization code 

FB$SEQ Sequential file organization 
FB$REL Relative file organization 
FB$IDX Indexed file organization 

FAB RAT Record handling mask 

FB$BLK Blocked records 

FB$CR Add CRLF to print record (LF-record-CR) 
FB$FTN FORTRAN-style carriage-control character in 
record 

FB$PRN VFC print record handling 

FAB RFM Record format code 

FB$UDF Undefined record format 

FB$FIX Fixed-length record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

FB$STM Stream record format 

FAB STS Completion status code 

FAB STV Completion status value 

KEY DAN Data area number 

KEY DBS Data area bucket size (blocks) 

KEY DFL Data bucket fill factor 

KEY DTP Key data type code 

XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

KEY DVB First data bucket virtual block number 
KEY FLG Index option mask 

XB$CHG Record key changes allowed on update 

XB$DUP Duplicate record keys allowed 

XB$INI No entries yet made in index 

XB$NUL Null record keys not indexed 

KEY IAN Higher level index area number 

KEY IBS Index area bucket size (blocks) 

KEY IFL Index bucket fill factor 

KEY LAN Lowest index level area number 

KEY LVL Number of index levels (not including data level) 

KEY MRL Minimum length of record containing key (bytes) 

KEY NSG Key segment count 

KEY NUL Null key character 

KEY POS Key segment positions 



(Continued on next page) 
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Table 5-38 (Cont.) : OPEN Output Fields 
Block Field Description 



KEY 


RVB 


Root index bucket virtual block number 


KEY 


SIZ 


Key segment sizes (bytes) 


KEY 


TKS 


Total key size (sum of key segment sizes) (bytes) 


NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESL 


Expanded string length (bytes) 


NAM 


FID 


File identifier 


NAM 


FNB 


File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default string 
Device in file string or default string 
Directory in file string or default string 
Quoted string in file string or default 
str ing 

File name in file string or default string 
File type in file string or default string 
File version in file string or default 
string 

Wildcard directory in file 
default string 

name in file 



type in file 



Wildcard file 
default string 
Wildcard file 
default string 
Wildcard file version 
default string 

Wildcard context established 



string or 
str ing 
str ing 



or 



or 



in 



file string or 



NAM 


RSL 


Resultant string length (bytes) 


(cleared) 


PRO 


PRG 


Programmer or member portion of 


file owner code 


PRO 


PRJ 


Project or group portion of file 


owner code 


PRO 


PRO 


File protection code 




SUM 


NOA 


Number of areas 




SUM 


NOK 


Number of indexes 




SUM 


PVN 


Prologue version number 
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5.20 $PARSE MACRO 

The $PARSE macro calls the PARSE operation routine to analyze a file 
speci f icat ion . 



FORMAT 

The format for the $PARSE is: 

$ PARSE f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the PARSE operation. 

If you supply a NAM block for the PARSE operation, the operation 
routine writes file information in its fields. This information is 
suitable as input to subsequent wildcard SEARCH operations. 

To supply a NAM block for the PARSE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the PARSE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB . 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecut i ve . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



File Specification 

The PARSE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 
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RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the PARSE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
PARSE operation uses no default string. 



Expanded String Buffer 

If you want the PARSE operation to return the expanded string for the 
file, provide a buffer for the string. If you want subsequent 
wildcard SEARCH operations to use the results of the PARSE operation, 
you must provide an expanded string buffer. 

Specify the address of the expanded string buffer in the 1-word ESA 
field of the NAM block. Specify the size (in bytes) of the expanded 
string buffer in the 1-byte ESS field of the NAM block; if you 
specify in the ESS field, the PARSE operation does not return the 
expanded string. 



Private Buffer Pool 

If you want the PARSE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the PARSE 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the PARSE operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 



RETURNED VALUES 



Wildcard Initialization 

If you supplied a NAM block to be initialized for wildcard SEARCH 
operations, the PARSE operation clears several fields: the 3-word DID 
field of the NAM block, the 1-byte RSL field of the NAM block, the 
1-word WCC field of the NAM block, and the 1-word WDI field of the NAM 
block. These cleared fields are part of the initialization for 
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subsequent wildcard SEARCH operations. 

The PARSE operation writes a match-pattern (for subsequent wildcard 
SEARCH operations) in the expanded string buffer, and writes the 
length (in bytes) of the expanded string in the 1-byte ESL field of 
the NAM block. 

The PARSE operation sets the NB$WCH mask in the 1-word FNB field of 
the NAM block, showing that wildcard information in the NAM block is 
initiali zed . 



Device Characteristics 

The PARSE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Device Identifier 

If you supply a NAM block, the PARSE operation writes a device 
identifier in the 2-word DVI field of the NAM block. 



File Specification Characteristics 

The PARSE operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. These masks and their meanings are: 



NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 



5-88 



OPERATION MACRO DESCRIPTIONS 
$ PARSE MACRO 



Expanded String 

If you supply a NAM block, and if the input file specification string 
does not contain wildcard characters, the PARSE operation writes the 
expanded string in the expanded string buffer; this string is a fully 
qualified file specification except that the file version number (if 
any) from the input file specification is unchanged. 



Completion Status and Value 

The PARSE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-39 lists control block fields that are input to the PARSE 
operation. Table 5-40 lists control block fields that are output by 
the PARSE operation. 



Table 5-39: PARSE Input Fields 



Block 


Field 


Description 


ALL 


NXT 


Next XAB address 


DAT 


NXT 


Next XAB address 


FAB 


BPA 


Private buffer pool address 


FAB 


BPS 


Private buffer pool size (bytes) 


FAB 


DNA 


Default string address 


FAB 


DNS 


Default string size (bytes) 


FAB 


FNA 


File string address 


FAB 


FNS 


File string size (bytes) 


FAB 


LCH 


Logical channel number 


FAB 


NAM 


NAM block address 


KEY 


NXT 


Next XAB address 


NAM 


ESA 


Expanded string buffer address 


NAM 


ESS 


Expanded string buffer size (bytes) 


PRO 


NXT 


Next XAB address 


SUM 


NXT 


Next XAB address 


Table 5-40: PARSE Output Fields 


Block 


Field 


Description 


FAB 


DEV 


Device characteristic mask 






FB$CCL Carriage-control device 






FB$MDI Multidirectory device 






FB$REC Record-oriented device 






FB$SDI Single-directory device 






FB$SQD Sequential device 






FB$TRM Terminal device 


FAB 


STS 


Completion status code 


FAB 


STV 


Completion status value 


NAM 


DID 


Directory identifier (cleared) 


NAM 


DVI 


Device identifier 


NAM 


ESL 


Expanded string length (bytes) 



(Continued on next page) 
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Table 5-40 (Cont.): PARSE Output Fields 
Block Field Description 



NAM 



FNB 



File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WCH 
NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 



Node in file string or default string 
Device in file string or default string 
Directory in file string or default string 
Quoted string in file string or default 
string 

File name in file string or default string 
File type in file string or default string 
File version in file string or default 
s tr ing 

Wildcard context established 

Wildcard directory in file string or 

default string 

Wildcard file name in file string 
default string 

Wildcard file type in file string 
default string 

Wildcard file version in file string 
default string 



or 



or 



or 



NAM RSL Resultant string length (bytes 
NAM WCC Wildcard context (cleared) 
NAM WDI Wildcard directory context (cleared) 



(cleared) 
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5.21 $POT MACRO (SEQUENTIAL ACCESS) 

The $PUT macro calls the PUT operation routine to transfer a record 
from a user buffer to an I/O buffer and to a file. 

The target of a sequential-access PUT operation depends on the file 
organi zat ion : 

• For a sequential file, the target of a sequential-access PUT 
operation is the end-of-file, and the next-record context must 
be the end-of-file. 

• For a relative file, the target of a sequential-access PUT 
operation is the next cell (as determined by the next-record 
context or by the context of an immediately preceding 
sequential access PUT operation) . 

• For an indexed file, a sequential-access PUT operation has no 
target; the PUT operation inserts the record and updates 
indexes. If the immediately preceding operation was also a 
sequential access PUT operation, the primary key value in your 
record must be greater than or equal to the primary key value 
of the preceding record. 



FORMAT 

The format for the $PUT is: 

$PUT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the PUT operation. 



OPTIONS 



Internal Stream Identifier 

The PUT operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the PUT operation asynchronously, set the 
RB$ ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the PUT operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Sequential Access 

Specify the RB$SEQ code in the 1-byte RAC field of the RAB. 
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Record 

Specify the address of the record to be transferred in the 1-word RBF 
field of the RAB f and the size (in bytes) of the record in the 1-word 
RSZ field of the RAB . 

If the record is in VFC format, specify the address of the 
fixed-length portion of the record in the 1-word RHB field of the RAB. 
If you specify in this field, the record header will be null-filled. 



Locate Mode 

For a sequential file, if you want the PUT operation to use locate 
mode, specify the address of the user buffer in the 1-word UBF field 
of the RAB, specify the maximum size of the record for the next PUT 
operation in the 1-word USZ field of the RAB, and set the RB$LOC mask 
in the 1-word ROP field of the RAB. 

The PUT operation returns (in the RBF field) the address of a location 
where your program can build the next record for output. The maximum 
next record size that you specify in the USZ field determines whether 
the next record can fit into an I/O buffer. 



Bucket Fill Number Honoring 

If you want the PUT operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the PUT operation fills buckets 
without regard to bucket fill numbers. 



Update Existing Record (Relative File) 

If you want to transfer the record to a cell in a relative file even 

if the cell contains a record, set the RB$UIF mask in the 1-word ROP 

field of the RAB. If you do not set this mask, and if the cell 

already contains a record, the PUT operation returns an error 
completion and does not transfer the record. 



Mass Insertion (Indexed File) 

For an indexed file, using mass- insert ion mode for a series of PUT 
operations speeds up the insertion of a series of records. To use 
mass-insertion mode for a series of records, set the RB$MAS mask in 
the 1-word ROP field of the RAB for each PUT operation in the series. 



STREAM CONTEXT 

The current-record and next-record contexts after a sequential access 
PUT operation are undefined. 
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RETURNED VALUES 



Next Record Buffer 

If you specified locate mode for the PUT operation, the PUT operation 
returns the address of a location where your program can build the 
next record for output in the 1-word RBF field of the RAB. This 
address gives a location in the I/O buffer (if there is room for 
another record there), or the location of your user buffer (if not). 



For a relative file or for a sequential disk file with fixed-length 
records, a sequential-access PUT operation returns the relative record 
number (RRN) for the inserted record in the 2-word BKT field of the 
RAB.. 



The PUT operation returns the record file address (RFA) for the 
inserted record in the 3-word RFA field of the RAB. 



Completion Status and Value 

The PUT operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-41 lists control block fields that are input to the PUT 
operation. Table 5-42 lists control block fields that are output by 
the PUT operation. 



RRN 



RFA 



Table 5-41: PUT (Sequential Access) Input Fields 



Block Field 



Description 



RAB 
RAB 



ISI 
RAC 



Internal stream identifier 
Record access code 



RB$SEQ 



Sequential access 



RAB 
RAB 
RAB 



RBF 
RHB 
ROP 



Record buffer address 

VFC control buffer address 

Record processing option mask 



RB$ASY 
RB$LOA 
RB$LOC 
RB$MAS 
RB$UIF 



Asynchronous operation 
Honor bucket fill numbers 
Locate mode 
Mass insert 

Update if record exists 



RAB 
RAB 
RAB 



RSZ 
UBF 
USZ 



Record size (bytes) 
User buffer address 
User buffer size (bytes) 
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Table 5-42: POT (Sequential Access) Output Fields 
Block Field Description 



RAB 


BKT 


Relative record number (RRN) 


RAB 


RFA 


Record file address 


RAB 


RBF 


Record buffer address 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.22 $PUT MACRO (KEY ACCESS) 

The $PUT macro calls the PUT operation routine to transfer a record 
from a user buffer to an I/O buffer and to a sequential disk file 
(with fixed-length records), a relative file, or an indexed file. 

The targ€it of a key-access PUT operation depends on the file 
organi zat ion : 

• For a sequential disk file (with fixed-length records) or a 
relative file, the key is a relative record number (RRN) , and 
the target of a key-access PUT operation is the cell specified 
by the RRN. 

• For an indexed file, a key-access PUT operation has no target; 
the PUT operation inserts the record and updates indexes. 



FORMAT 

The format for the $PUT is: 

$PUT rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the PUT operation. 



OPTIONS 



Internal Stream Identifier 

The PUT operation reads the internal stream identifier from the 1-word 
ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the PUT operation asynchronously, set the 
RB$AS Y mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the PUT operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Key Access 

Specify the RB$KEY code in the 1-byte RAC field of the RAB. 



Record 

Specify the address of the record to be transferred in the 1-word RBF 
field of the RAB, and the size (in bytes) of the record in the 1-word 
RSZ field of the RAB. 
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If the record is in VFC format, specify the address of the 
fixed-length portion of the record in the 1-word RHB field of the RAB. 
If you specify in this field, the record header will be null-filled. 



Record Buffer 

Specify a record buffer for the PUT operation; specify the address of 
the record buffer in the 1-word UBF field of the RAB ; specify the 
size (in bytes) of the record buffer in the 1-word USZ field of the 
RAB . 

Note that the value in the UBF field will be used (copied to the RBF 
field) only if you specify locate mode. A request for locate mode is 
otherwise ignored for a key access PUT operation. 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, specify a 4-byte relative record number (RRN) in the 1-word 
KBF field of the RAB, and specify or 4 in the 1-byte KSZ field of 
the RAB. 



Bucket Fill Number Honoring 

If you want the PUT operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the PUT operation fills buckets 
without regard to bucket fill numbers. 



Update Existing Record (Relative File) 

If you want to transfer the record to a cell in a relative file even 

if the cell contains a record, set the RB$UIF mask in the 1-word ROP 

field of the RAB. If you do not set this mask, and if the cell 

already contains a record, the PUT operation returns an error 
completion and does not transfer the record. 



STREAM CONTEXT 

The current-record context after a key access PUT operation is 
undefined; the next-record context is unchanged. 



RETURNED VALUES 



RRN 

For a relative file or for a sequential disk file with fixed-length 
records, a key-access PUT operation returns the relative record number 
(RRN) for the inserted record in the 2-word BKT field of the RAB. 



RFA 

The PUT operation returns the record file address (RFA) for the 
inserted record in the 3-word RFA field of the RAB. 



5-96 



OPERATION MACRO DESCRIPTIONS 
$PDT MACRO (KEY ACCESS) 



Completion Status and Value 

The PUT operation returns completion status in the 1-word STS field of 
the RAB and returns a completion value in the 1-word STV field of the 
RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-43 lists control block fields that are input to the PUT 
operation. Table 5-44 lists control block fields that are output by 
the PUT operation. 



Table 5-43: PUT (Key Access) Input Fields 
Block Field Description 



RAB ISI Internal stream identifier 

RAB KBF Key buffer address 

RAB KSZ Key size (bytes) 

RAB RAC Record access code 

RB$KEY Key access 

RAB RBF Record buffer address 

RAB RHB VFC control buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RB$LOA Honor bucket fill numbers 

RB$LOC Locate mode 

RB$UIF Update if record exists 

RAB RSZ Record size (bytes) 
RAB UBF User buffer address 
RAB USZ User buffer size (bytes) 



Table 5-44: PUT (Key Access) Output Fields 
Block Field Description 



RAB 


BKT 


Relative record number (RRN) 


RAB 


RBF 


Record buffer address 


RAB 


RFA 


Record file address 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.23 $READ MACRO (SEQUENTIAL ACCESS) 

The $READ macro calls the READ operation routine to transfer blocks 
from a file to an I/O buffer. The target of a sequential-access READ 
operation is the readable block (and, for a multiblock READ operation, 
following blocks) . 



FORMAT 

The format for the $READ is: 

$READ rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the READ operation. 



OPTIONS 



Internal Stream Identifier 

The READ operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Block Specification 

For a sequential-access READ operation, specify in the 2-word BKT 
field of the RAB. 



User Buffer 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

For a magtape file, the READ operation reads at most one magtape block 
into the buffer; for other files, the READ operation fills the buffer 
(unless it reached the end-of-file before the buffer is filled). 



Asynchronous Operation 

If you want to execute the READ operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the READ operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The readable-block context after a READ operation is the block 

following the last-read block; the writable-block context is the 
first-read block. 
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RETURNED VALUES 



Data Blocks 

The READ operation returns the address and length of the data read 
from the file. The value in the 1-word RBF field of the RAB is the 
address of the data read; the value in the 1-word RSZ field of the 
RAB is the length (in bytes) of the data read. 

The READ operation normally will not read beyond the logical 
end-of-file. For sequential files with undefined (UDF) record format, 
however, the READ operation will respect the logical end-of-file 
marker only if you have specified no write-sharing in the 1-byte SHR 
field of the FAB. If you specify write-sharing, RMS-11 will ignore 
the logical end-of-file marker and will stop only at the physical 
end-of-file on the disk. 



Record File Address (RFA) 

The READ operation returns the virtual block number of the first-read 

block in the first two words of the 3-word RFA field of the RAB (it 
clears the third word) . 



Completion Status and Value 

The READ operation returns completion status in the 1-word STS field 

of the RAB and returns a completion value in the 1-word STV field of 

the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-45 lists control block fields that are input to the READ 
operation. Table 5-46 lists control block fields that are output by 
the READ operation. 



Table 5-45: READ (Sequential Access) Input Fields 



Block Field Description 



RAB BKT Virtual block number (VBN) 
RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-46: READ (Sequential Access) Output Fields 
Block Field Description 



RAB 


RBF 


Record buffer address 


RAB 


RFA 


Virtual block number (2 words) 


RAB 


RSZ 


Record size (bytes) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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5.24 $READ MACRO (VBN ACCESS) 

The $READ macro calls the READ operation routine to transfer blocks 
from a file to an I/O buffer. The target of a VBN-access READ 
operation is a specified block (and, for a multiblock READ operation, 
following blocks) . 



FORMAT 

The format for the $READ is: 

$READ rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the READ operation. 



OPTIONS 



Internal Stream Identifier 

The READ operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Block Specification 

Specify the virtual block number of the first block to be read in the 
2-word BKT field of the RAB. 



User Buffer 

Specify the address of the user buffer in the 1-word UBF field of the 
RAB, and specify the size (in bytes) of the user buffer in the 1-word 
USZ field of the RAB. 

For a magtape file, the READ operation reads at most one magtape block 
into the buffer; for other files, the READ operation fills the buffer 
(unless it reached the end-of-file before the buffer is filled). 



Asynchronous Operation 

If you want to execute the READ operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the READ operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The readable-block context after a READ operation is the block 

following the last-read block; the writable-block context is the 
first-read block. 
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RETURNED VALUES 



Data Blocks 

The READ operation returns the address and length of the data read 
from the file. The value in the 1-word RBF field of the RAB is the 
address of the data read; the value in the 1-word RSZ field of the 
RAB is the length (in bytes) of the data read. 

The READ operation normally will not read beyond the logical 
end-of-file. For sequential files with undefined (UDF) record format, 
however, the READ operation will respect the logical end-of-file 
marker only if you have specified no write-shar ing in the 1-byte SHR 
field of the FAB. If you specify wr ite-sharing , RMS-11 will ignore 
the logical end-of-file marker and will stop only at the physical 
end-of-file on the disk. 



Record File Address (RFA) 

The READ operation returns the virtual block number of the first-read 
block in the first two words of the 3-word RFA field of the RAB (it 
clears the third word) . 



Completion Status and Value 

The READ operation returns completion status in the 1-word STS field 

of the RAB and returns a completion value in the 1-word STV field of 

the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-47 lists control block fields that are input to the READ 
operation. Table 5-48 lists control block fields that are output by 
the READ operation. 



Table 5-47: READ (VBN Access) Input Fields 
Block Field Description 



RAB BKT Virtual block number (VBN) 
RAB ISI Internal stream identifier 
RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RAB UBF User buffer address 

RAB USZ User buffer size (bytes) 



Table 5-48: READ (VBN Access) Output Fields 
Block Field Description 



RAB 


RBF 


Record buffer address 


RAB 


RFA 


Virtual block number (2 words) 


RAB 


RSZ 


Record size (bytes) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 



5-101 



OPERATION MACRO DESCRIPTIONS 
$ REMOVE MACRO 



5.25 $ REMOVE MACRO 

The $REMOVE macro calls the REMOVE operation routine to remove the 
directory entry for a file. 



FORMAT 

The format for the $REMOVE is: 

$ REMOVE f abaddr [ , [erraddr] [ ,sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the REMOVE operation. 

If you supply a NAM block and specify remove by NAM block, the REMOVE 
operation reads NAM block fields to obtain identifiers for the target 
file. 

To supply a NAM block for the REMOVE operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the REMOVE 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB . 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



File Specification (Nonwildcard REMOVE Operation) 

The REMOVE operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string). 
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RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the REMOVE 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
REMOVE operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the REMOVE operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the REMOVE operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 



Remove by Wildcard Specification 

You can use the REMOVE operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation is removed without affecting 
fields that are used as context for subsequent SEARCH operations. 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
REMOVE operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section . ) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the REMOVE operation removes its directory entry; if 
not, the REMOVE operation does not remove a directory entry, but 
instead passes control block data from the SEARCH operation (in 
particular, the ER$NMF completion status code and the cleared NB$WCH 
mask in the 1-word FNB field of the NAM block) . 
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Expanded String Buffer 

If you want the REMOVE operation to return the expanded string for the 

file whose directory entry was removed, provide a buffer for the 

string. Specify the address of the expanded string buffer in the 

1-word ESA field of the NAM block. Specify the size (in bytes) of the 

expanded string buffer in the 1-byte ESS field of the NAM block; if 
you specify in the ESS field, the REMOVE operation does not return 
the expanded string. 



Private Buffer Pool 

If you want the REMOVE operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the REMOVE 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the REMOVE operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 



RETURNED VALUES 



Device Characteristics 

The REMOVE operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 
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Device, Directory, and File Identifiers 

If you supply a NAM block, the REMOVE operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 



Expanded String 

If you specify a buffer for the expanded string for the file (ESA and 
ESS fields in the NAM block) , the REMOVE operation writes the expanded 
string for the target file in this buffer, and writes the length (in 
bytes) of the string in the 1-byte ESL field of the NAM block. 



File Specification Characteristics 



The REMOVE operation sets the masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. 



These; masks and their meaning are: 



NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 



Wildcarding 

The REMOVE operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
REMOVE operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 



Completion Status and Value 

The REMOVE operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-49 lists control block fields that are input to the REMOVE 
operation. Table 5-50 lists control block fields that are output by 
the REMOVE operation. 
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Table 5-49: REMOVE Input Fields 
Block Field Description 



ALL NXT Next XAB address 

DAT NXT Next XAB address 

FAB BPA Private buffer pool address 

FAB BPS Private buffer pool size (bytes) 

FAB DNA Default string address 

FAB DNS Default string size (bytes) 

FAB FNA File string address 

FAB FNS File string size (bytes) 

FAB FOP File processing option mask 

FB$FID Use information in NAM block 

FAB LCH Logical channel number 

FAB NAM NAM block address 

KEY NXT Next XAB address 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESA Expanded string buffer address 

NAM ESS Expanded string buffer size (bytes) 

NAM FID File identifier 

NAM FNB File specification mask 

NB$WCH Wildcard context established 

PRO NXT Next XAB address 

SUM NXT Next XAB address 



Table 5-50: REMOVE Output Fields 
Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 



FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes] 

NAM FID File identifier 



(Continued on next page) 
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Table 5-50 (Cont.) : REMOVE Output Fields 
Block E'ield Description 



NAM 



FNB 



File specification mask 



NB$NOD Node in file string or default string 
NB$DEV Device in file string or default string 
NB$DIR Directory in file string or default string 
NB$QUO Quoted string in file string or default 
string 

NB$NAM File name in file string or default string 
NB$TYP File type in file string or default string 
NB$VER File version in file string or default 
string 

NB$WDI Wildcard directory in file string or 

default string 
NB$WNA Wildcard file name in file string 

default string 
NB$WTY Wildcard file type in file string 

default string 
NB$WVE Wildcard file version in file string or 

default string 
NB$WCH Wildcard context established (cleared) 



or 



or 



NAM 



RSL 



Resultant string length (bytes) 
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5.26 $ RENAME MACRO 

The $RENAME macro calls the RENAME operation routine to change the 
directory entry for a file. 

The old and new entries (file specifications) must have the same 
network node and device specifications. 



FORMAT 

The format for the $RENAME is: 

$ RENAME oldfabaddr , [erraddr] , [sucaddr] , newfabaddr 

where oldfabaddr is the address of the FAB for the operation; erraddr 
is the address of the error handler for the operation; sucaddr is the 
address of the success handler for the operation; and newfabaddr is 
the address of the FAB giving the new file specification. 



CONTROL BLOCKS 

You must supply two FABs for the RENAME operation: an "old" FAB 
containing the current specification for the file, and a "new" FAB 
containing the new specification for the file. 

If you supply a NAM block for the old FAB (old NAM block) and specify 
either rename by NAM block or wildcarding, the RENAME operation reads 
its fields to obtain identifiers for the old file specification. If 
you supply a NAM block for the new FAB (new NAM block) and specify 
rename by NAM block, the RENAME operation reads its fields to obtain 
identifiers for the new file specification. 

To supply a NAM block for the RENAME operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the RENAME 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecu t i ve . 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



Old File Specification (Nonwildcard RENAME Operation) 

The RENAME operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string). 
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RMS-11 defaults are: 

• Device — The device to which the specified logical channel is 
assigned, or SY: if the specified logical channel is not 
assigned to any device. 

• Directory — The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB . Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the RENAME 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
RENAME operation uses no default string. 

If you set the FB$FID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the RENAME operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the RENAME operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 



Old File Specification (Wildcard RENAME Operation) 

You can use the RENAME operation in a wildcarding program loop. (The 
NB$WCH mask in the 1-word FNB field of the NAM block will already have 
been set by an earlier PARSE operation.) 

If you set the FB$FID mask in the 1-word FOP field of the FAB, the 
file found by a previous SEARCH operation is renamed without affecting 
fields that are used as context for subsequent SEARCH operations. 

If you clear the FB$FID mask in the 1-word FOP field of the FAB, the 
RENAME operation first performs an implicit SEARCH operation. (The 
input and output fields for the SEARCH operation are not described 
here and are not included in the checklists at the end of this 
section . ) 

If the SEARCH operation finds a file that matches the wildcard file 
specification, the RENAME operation replaces its directory entry; if 
not, the RENAME operation does not replace a directory entry, but 
instead passes control block data from the SEARCH operation (in 
particular, the ER$NMF completion status code and the cleared NB$WCH 
mask in the 1-word FNB field of the NAM block) . 



New File Specification 

The RENAME operation constructs the full file specification from the 
file string, the default string (which contributes only elements not 
present in the file string), and RMS-11 defaults (which contribute 
elements not present in either the file string or the default string) . 



5-109 



OPERATION MACRO DESCRIPTIONS 
$ RENAME MACRO 



RMS-11 defaults are: 

• Device — The device that was used for the old file 
specification (The old FAB logical channel is used, and the 
new FAB logical channel is ignored) . 

• Directory -- The current directory for the task. 

• Name, type, version — Defaulted to null. 

The file string and the default string must not contain wildcards. 

Specify the address of the file string in the 1-word FNA field of the 
FAB. Specify the size (in bytes) of the file string in the 1-byte FNS 
field of the FAB; if you specify in the FNS field, the RENAME 
operation uses no file string. 

Specify the address of the default string in the 1-word DNA field of 
the FAB. Specify the size (in bytes) of the default string in the 
1-byte DNS field of the FAB; if you specify in the DNS field, the 
RENAME operation uses no default string. 

If you set the FB$F ID mask in the 1-word FOP field of the FAB and 
supply a NAM block, the RENAME operation reads the device identifier 
from the 2-word DVI field of the NAM block; if this value is nonzero, 
the specified device overrides the device in the merged string. 

In the same circumstance, the RENAME operation reads the directory 
identifier from the 3-word DID field of the NAM block; if this value 
is nonzero, the specified directory overrides the directory in the 
merged string. 



Private Buffer Pool 

If you want the RENAME operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the RENAME 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the RENAME operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 



Expanded String Buffers 

If you want the expanded string for the file given by a FAB returned 
to a buffer, supply a NAM block for the FAB. Specify the address of 
the buffer in the 1-word ESA field of the NAM block, and the size (in 
bytes) of the buffer in the 1-byte ESS field of the NAM block. If you 
do not supply a NAM block for a FAB, or if you specify in the ESS 
field, the RENAME operation does not return the expanded string. 
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RETURNED VALUES 



Expanded Strings 

If you specify a buffer for the expanded string for a FAB (ESA and ESS 
fields in the NAM block) , the RENAME operation writes the expanded 
string in the buffer, and writes the length (in bytes) of the string 
in the 1-byte ESL field of the NAM block. 



Device Characteristics 

The RENAME operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set) ; RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MD I mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB). 

• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$ REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Device, Directory, and File Identifiers 

If you supply a NAM block, the RENAME operation writes a device 
identifier in the 2-word DVI field of the NAM block, a directory 
identifier in the 3-word DID field of the NAM block, and a file 
identifier in the 3-word FID field of the NAM block. 



File Specification Characteristics 

The RENAME operation sets masks in the 1-word FNB field of the NAM 
block to show which file specification elements were present in the 
file string and default string. 

These masks and their meaning are: 



NB$NOD Node in file string or default string 

NB$DEV Device in file string or default string 

NB$DIR Directory in file string or default string 

NB$QUO Quoted string in file string or default string 

NB$NAM File name in file string or default string 

NB$TYP File type in file string or default string 

NB$VER File version in file string or default string 

NB$WDI Wildcard directory in file string or default string 

NB$WNA Wildcard file name in file string or default string 

NB$WTY Wildcard file type in file string or default string 

NB$WVE Wildcard file version in file string or default string 
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Wildcarding 

The RENAME operation clears the NB$WCH mask in the 1-word FNB field of 
the NAM block; this shows that no wildcard context exists after the 
RENAME operation. It also clears the 1-byte RSL field of the NAM 
block to show that no resultant string was returned. 



Completion Status and Value 

The RENAME operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-51 lists control block fields that are input to the RENAME 
operation. Table 5-52 lists control block fields that are output by 
the RENAME operation. 



NOTE 

The only input fields taken from both 
the "old" and the "new" FABs are the 
DNA, DNS, FNA , FNS, FOP, and NAM fields. 
All other FAB input fields are taken 
from the "old" FAB only. All FAB output 
fields are returned to the "old" FAB 
only . 



Table 5-51: RENAME Input Fields 
Block Field Description 



ALL 


NXT 


Next XAB address 


DAT 


NXT 


Next XAB address 


FAB 


BPA 


Private buffer pool address 


FAB 


BPS 


Private buffer pool size (bytes) 


FAB 


DNA 


Default string address 


FAB 


DNS 


Default string size (bytes) 


FAB 


FNA 


File string address 


FAB 


FNS 


File string size (bytes) 


FAB 


FOP 


File processing option mask 






FB$FID Use information in NAM block 


FAB 


LCH 


Logical channel number 


FAB 


NAM 


NAM block address 


KEY 


NXT 


Next XAB address 


NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESA 


Expanded string buffer address 


NAM 


ESS 


Expanded string buffer size (bytes) 


NAM 


FNB 


File specification mask 






NB$WCH Wildcard context established 


PRO 


NXT 


Next XAB address 


SUM 


NXT 


Next XAB address 
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Table 5-52: RENAME Output Fields 
Block Field Description 



FAB 



DEV 



Device characteristic mask 



FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM DVI Device identifier 

NAM ESL Expanded string length (bytes) 

NAM FID File identifier 

NAM FNB File specification mask 



NB$NOD 
NB$DEV 
NB$DIR 
NB$QUO 

NB$NAM 
NB$TYP 
NB$VER 

NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 

NB$WCH 



Node in file string or default string 
Device in file string or default string 
Directory in file string or default string 
Quoted string in file string or default 
string 

File name in file string or default string 
File type in file string or default string 
File version in file string or default 
s tr ing 

Wildcard directory in 
default string 



file string 



or 



in 



in 



Wildcard file name 
default string 
Wildcard file type 
default string 
Wildcard file version 
default string 

Wildcard context established 



file string or 



in 



file string or 
file string or 



(cleared) 



NAM 



RSL 



Resultant string length (bytes] 
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5.27 $ REWIND MACRO 

The $REWIND macro calls the REWIND operation routine to reset the 
context for a stream to the beginning-of-f i le. The file can have any 
organi zat ion . 



FORMAT 

The format for the $REWIND is: 

$REWIND rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the REWIND operation. 



OPTIONS 



Internal Stream Identifier 

The REWIND operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Key of Reference 

For an indexed file, you must specify the index that the stream will 
use in accessing records. Specify this key of reference in the 1-byte 
KRF field of the RAB. This value matches the value in the file's KEY 
block for the index: for the primary index, 1 for the first 
alternate index, and so forth. 



Asynchronous Operation 

If you want to execute the REWIND operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the REWIND operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

For a record access file, the current context after a REWIND operation 
is undefined and the next-record context is the first record in the 
file; for an indexed file, this first record is defined by the 
specified index. 

For a block access file, both the readable-block and writable-block 
contexts after a REWIND operation are the first block in the file. 
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RETURNED VALUES 



Completion Status and Value 

The REWIND operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-53 lists control block fields that are input to the REWIND 
operation. Table 5-54 lists control block fields that are output by 
the REWIND operation. 



Table 5-53: REWIND Input Fields 



Block 


Field 


Description 


RAB 
RAB 
RAB 


ISI 
KRF 
ROP 


Internal stream identifier 

Key of reference 

Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-54: REWIND Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.28 $ SEARCH MACRO 

The $SEARCH macro calls the SEARCH operation routine to scan a 
directory and return a file specification and identifiers in NAM block 
fields. You should precede the SEARCH operation by a PARSE operation, 
which initializes the NAM block fields for the SEARCH operation. 

The SEARCH operation finds a file specification that matches the 
match-pattern initialized (in the expanded string buffer) by the PARSE 
operation; a series of wildcard SEARCH operations returns successive 
matching file specifications. 



FORMAT 

The format for the $SEARCH is: 

$SEARCH f abaddr [ , [erraddr] [ , sucaddr] ] 

where fabaddr is the address of the FAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a FAB for the SEARCH operation. 

You must supply a NAM block for the SEARCH operation. 

To supply a NAM block for the SEARCH operation, specify the address of 
the NAM block in the 1-word NAM field of the FAB. 

To supply XABs (ALL, DAT, KEY, PRO, and SUM blocks) for the SEARCH 
operation, specify the address of the first XAB in the 1-word XAB 
field of the FAB; specify the address of the next XAB (if any) in the 
1-word NXT field of each XAB; specify in the NXT field of the last 
XAB. 

All KEY blocks must be together in the chain of XABs, and must be in 
ascending order (by the index reference number in the 1-byte REF field 
of the KEY block) ; the index reference numbers need not be 
consecutive. 

All ALL blocks must be together in the chain of XABs, and must be in 
ascending order (by the area identifier in the 1-byte AID field of the 
ALL block); the area identifiers need not be consecutive. 

Multiple DAT, PRO, or SUM XABs are illegal. 



OPTIONS 



Wildcard Context Information 

The SEARCH operation reads NAM block fields that are initialized, 
written, or preserved by a preceding PARSE or wildcard SEARCH 
operation: the 3-word DID field of the NAM block, the 2-word DVI 
field of the NAM block, the 1-word ESA field of the NAM block, the 
1-byte ESL field of the NAM block, the NB$WCH mask in the 1-word FNB 
field of the NAM block, the 1-word RSA field of the NAM block, the 
1-byte RSL field of the NAM block, the 1-byte RSS field of the NAM 
block, the 1-word WCC field of the NAM block, and the 1-word WDI field 
of the NAM block. 
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The SEARCH operation also uses the expanded string in the expanded 
string buffer. 

You must preserve these fields between a PARSE and a SEARCH operation 
and between successive wildcard SEARCH operations. 



Private Buffer Pool 

If you want the SEARCH operation to use a private buffer pool instead 
of the central buffer pool, specify the address of the (word-aligned) 
private buffer pool in the 1-word BPA field of the FAB, and its size 
(in bytes) in the 1-word BPS field of the FAB; this size must be a 
multiple of 4. 

If you specify in either the BPA field or the BPS field, the SEARCH 
operation uses the central buffer pool. 



Logical Channel 

Specify the logical channel for the SEARCH operation in the 1-byte LCH 
field of the FAB. The logical channel number must not be the same as 
the logical channel number for any already-open file, and must not be 
0. 



Magtape Positioning 

The FB$RWO mask in the 1-word FOP field of the FAB may be set to cause 
a magtape to be rewound prior to the first wildcard SEARCH operation. 
To avoid unpredictable results, the FB$RWO mask in the 1-word FOP 
field of the FAB and FB$RWC mask in the 1-word FOP field of the FAB 
should not be set thereafter. 



RETURNED VALUES 



Resultant String 

The SEARCH operation writes the full file specification for the found 

file in the resultant string buffer, and writes the length of the 

string in the 1-byte RSL field of the NAM block. 



Device Characteristics 

The SEARCH operation returns device characteristics as masks in the 
1-byte DEV field of the FAB. The device characteristics are: 

• Printer or terminal (indicated by the set FB$CCL mask in the 
1-byte DEV field of the FAB and the set FB$REC mask in the 
1-byte DEV field of the FAB; for a terminal, the FB$TRM mask 
in the 1-byte DEV field of the FAB is also set); RMS-11 
treats a printer or terminal as a unit-record device. 

• Disk, DECtape, or DECTAPE II (indicated by the set FB$MDI mask 
in the 1-byte DEV field of the FAB); RMS-11 treats a disk, 
DECtape, or DECTAPE II as a disk device. 

• Unit-record device (indicated by the set FB$REC mask in the 
1-byte DEV field of the FAB) . 
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• Non-ANSI magtape or cassette tape (indicated by the set FB$SDI 
mask in the 1-byte DEV field of the FAB and the set FB$REC 
mask in the 1-byte DEV field of the FAB) ; RMS-11 treats a 
non-ANSI magtape or a cassette tape as a unit-record device. 

• ANSI-format magtape (indicated by the set FB$SQD mask in the 
1-byte DEV field of the FAB) . 



Directory and File Identifiers 

If the SEARCH operation finds a file that matches the wildcard 
pattern, it writes the directory identifier for the found file in the 
3-word DID field of the NAM block, and the file identifier in the 
3-word FID field of the NAM block. 



Wildcard Context Information 

The SEARCH operation writes the wildcard context in the 1-word WCC 
field of the NAM block, and the wildcard directory context in the 
1-word WD I field of the NAM block. 

If the SEARCH operation did not find a matching file, it clears the 
NB$WCH mask in the 1-word FNB field of the NAM block; this shows that 
no further wildcarding is possible using the current wildcard 
information . 



Completion Status and Value 

The SEARCH operation returns completion status in the 1-word STS field 
of the FAB and returns a completion value in the 1-word STV field of 
the FAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-55 lists control block fields that are input to the SEARCH 
operation. Table 5-56 lists control block fields that are output by 
the SEARCH operation. 



Table 5-55: SEARCH Input Fields 



Block Field 



Description 



ALL 
DAT 
FAB 
FAB 
FAB 



NXT 
NXT 
BPA 
BPS 
FOP 



Next XAB address 

Next XAB address 

Private buffer pool address 

Private buffer pool size (bytes) 

File processing option mask 



FB$RWO 
FB$RWC 



Rewind magtape before operation 
Rewind magtape after closing file 



FAB 
FAB 
KEY 



LCH 
NAM 
NXT 



Logical channel number 
NAM block address 
Next XAB address 



(Continued on next page) 
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Table 5-55 (Cont.): SEARCH Input Fields 
Block Field Description 



NAM 


DID 


Directory identifier 


NAM 


DVI 


Device identifier 


NAM 


ESA 


Expanded string buffer address 


NAM 


ESL 


Expanded string length (bytes) 


NAM 


FNB 


File specification mask 






NB$WCH Wildcard context establishes 


NAM 


RSA 


Resultant string buffer address 


NAM 


RSL 


Resultant string length (bytes) 


NAM 


RSS 


Resultant string buffer size (bytes) 


NAM 


WCC 


Wildcard context 


NAM 


WD I 


Wildcard directory context 


PRO 


NXT 


Next XAB address 


SUM 


NXT 


Next XAB address 



Table 5-56: SEARCH Output Fields 
Block Field Description 



FAB DEV Device characteristic mask 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

FB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

FAB STS Completion status code 

FAB STV Completion status value 

NAM DID Directory identifier 

NAM FID File identifier 

NAM FNB File specification mask 

NB$WCH Wildcard context established 

NAM RSL Resultant string length (bytes) 

NAM WCC Wildcard context 

NAM WDI Wildcard directory context 
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5.29 $SPACE MACRO 

The $SPACE macro calls the SPACE operation routine to move a magtape 
backward or forward. 



FORMAT 

The format for the $SPACE is: 

$SPACE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the SPACE operation. 



OPTIONS 



Internal Stream Identifier 

The SPACE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Spacing Interval 

Specify the number of blocks to move the magtape in the first word of 
the 2-word BKT field of the RAB. A positive number spaces forward; a 
negative number spaces backward. 

Asynchronous Operation 

If you want to execute the SPACE operation asynchronously, set the 
RB$ AS Y mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the SPACE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The readable-block context after a SPACE operation is the target 
block; the writable-block context after a SPACE operation is the 
target block. 



RETURNED VALUES 



Completion Status and Value 

The SPACE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 
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CHECKLISTS 

Table 5-57 lists control block fields that are input to the SPACE 
operation. Table 5-58 lists control block fields that are output by 
the SPACE operation. 



Table 5-57: SPACE Input Fields 



Block 


Field 


Description 


RAB 
RAB 
RAB 


BKT 
ISI 
ROP 


Virtual block number (VBN) increment 
Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-58: SPACE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.30 $TRUNCATE MACRO 

The $TRUNCATE macro calls the TRUNCATE operation routine to remove 
records from the latter part of a sequential file; records are 
removed inclusively from the current record through the end-of-file. 
If the file cannot be truncated, the TRUNCATE operation returns an 
error completion and leaves the current-record context undefined and 
the next-record context unchanged. 



FORMAT 

The format for the $TRUNCATE is: 

$TRUNCATE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the TRUNCATE operation. 



OPTIONS 



Internal Stream Identifier 

The TRUNCATE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Asynchronous Operation 

If you want to execute the TRUNCATE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the TRUNCATE operation executes synchronously. (Your 
program must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



STREAM CONTEXT 

The TRUNCATE operation destroys the current-record context; the 
next-record context after the TRUNCATE operation is the end-of-file. 



RETURNED VALUES 



Completion Status and Value 

The TRUNCATE operation returns completion status in the 1-word STS 
field of the RAB and returns a completion value in the 1-word STV 
field of the RAB. Appendix A lists completion status symbols and 
values . 
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CHECKLISTS 

Table 5-59 lists control block fields that are input to the TRUNCATE 
operation. Table 5-60 lists control block fields that are output by 
the TRUNCATE operation. 



Table 5-59: TRUNCATE Input Fields 



Block 


Field 


Description 


RAB 
RAB 


ISI 
ROP 


Internal stream identifier 
Record processing option mask 

RB$ASY Asynchronous operation 


Table 5-60: TRUNCATE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.31 $ UPDATE MACRO 

The $UPDATE macro calls the UPDATE operation routine to transfer a 
record from a user buffer to a disk file (overwriting the existing 
record). The target of the UPDATE operation is the current record, 
which is overwritten. 

If no record (as specified in the RAB) can be transferred, the UPDATE 
operation returns an error completion. 



FORMAT 

The format for the $UPDATE is: 

$UPDATE rabaddr [ , [erraddr] [,sucaddr]] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the UPDATE operation. 



OPTIONS 



Internal Stream Identifier 

The UPDATE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB, and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. For sequential files and for indexed 
files in which duplicate primary key values are permitted, the size of 
the buffer must be the same as the size of the existing record. 

If the file has VFC format, specify the address of the buffer for the 
VFC header in the 1-word RHB field of the RAB; if you specify zero in 
this field, the existing record header will remain unchanged. 



Asynchronous Operation 

If you want to execute the UPDATE operation asynchronously, set the 
RB$ AS Y mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the UPDATE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 



Bucket Fill Number Honoring 

If you want the UPDATE operation to honor bucket fill numbers for the 
file and its areas, set the RB$LOA mask in the 1-word ROP field of the 
RAB. If you do not set this mask, the UPDATE operation fills buckets 
without regard to bucket fill numbers. 
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STREAM CONTEXT 

The UPDATE operation destroys the current-record context; the 
next-record context after the UPDATE operation is unchanged. 



RETURNED VALUES 



Completion Status and Value 

The UPDATE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-61 lists control block fields that are input to the UPDATE 
operation. Table 5-62 lists control block fields that are output by 
the UPDATE operation. 



Table 5-61: UPDATE Input Fields 



Block 


Field 


Description 


RAB 
RAB 
RAB 
RAB 


ISI 
RBF 
RHB 
ROP 


Internal stream identifier 
Record buffer address 
VFC control buffer address 
Record processing option mask 

RB$ASY Asynchronous operation 
RB$LOA Honor bucket fill numbers 


RAB 


RSZ 


Record size (bytes) 


Table 5-62: UPDATE Output Fields 


Block 


Field 


Description 


RAB 
RAB 


STS 
STV 


Completion status code 
Completion status value 
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5.32 $WAIT MACRO 

The $WAIT macro calls the WAIT operation routine to suspend processing 
until an outstanding asynchronous operation on the stream is 
completed. The WAIT operation does not affect stream context. The 
WAIT operation cannot be used within any asynchronous operation's 
completion routine. 

FORMAT 

The format for the $WAIT is: 
$WAIT rabaddr 

where rabaddr is the address of the RAB for the operation. 
CONTROL BLOCKS 

You must supply a RAB for the WAIT operation. 
OPTIONS 

Internal Stream Identifier 

The WAIT operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 

STREAM CONTEXT 

The WAIT operation does not affect stream context. The stream context 
after the WAIT operation is the context established by the outstanding 
asynchronous operation; if there is no outstanding asynchronous 
operation for the stream, the stream context is unchanged. 

RETURNED VALUES 

The WAIT operation returns no values. 
CHECKLISTS 

Table 5-63 lists control block fields that are input to the WAIT 
operation . 



Table 5-63: WAIT Input Fields 



Block 


Field 


Description 


RAB 


ISI 


Internal stream identifier 
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5.33 $WRITE MACRO (SEQUENTIAL ACCESS) 

The $WRITE macro calls the WRITE operation routine to write blocks to 
a file. The target of a sequential-access WRITE operation is the 
writable block (and, for a multiblock WRITE operation, following 
blocks) . 



FORMAT 

The format for the $WRITE is: 

$WRITE rabaddr [ , [erraddr] [ ,sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the WRITE operation. 



OPTIONS 



Internal Stream Identifier 

The WRITE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Block Identification 

For a sequential-access WRITE operation, specify in the 2-word BKT 
field of the RAB . 



Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB , and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. You must specify a record buffer for the 
WRITE operation; the WRITE operation transfers data from this buffer 
to the file. 

The WRITE operation normally updates the logical end-of-file marker, 
when appropriate, and automatically extends the file's allocation, 
when necessary. For sequential files with undefined (UDF) record 
format, however, the WRITE operation updates the logical end-of-file 
marker and performs automatic file extensions only if no write-shar ing 
has been specified in the 1-byte SHR field of the FAB. 



Asynchronous Operation 

If you want to execute the WRITE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the WRITE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 
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STREAM CONTEXT 

The readable-block context after a WRITE operation is the block 
following the last-written block; the writable-block context after a 
WRITE operation is the block following the last-written block. 



RETURNED VALUES 



Record File Address (RFA) 

The WRITE operation returns the virtual block number of the 
first-written block in the first two words of the 3-word RFA field of 
the RAB (it clears the third word) . 



Completion Status and Value 

The WRITE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-64 lists control block fields that are input to the WRITE 
operation. Table 5-65 lists control block fields that are output by 
the WRITE operation. 



Table 5-64: WRITE (Sequential Access) Input Fields 



Block Field Description 



RAB BKT Virtual block number (VBN) 

RAB ISI Internal stream identifier 

RAB RBF Record buffer address 

RAB ROP Record processing option mask 

RB$ASY Asynchronous operation 

RAB RSZ Record size (bytes) 



Table 5-65: WRITE (Sequential Access) Output Fields 



Block Field Description 



RAB RFA Virtual block number (2 words) 
RAB STS Completion status code 
RAB STV Completion status value 
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5.34 $WRITE MACRO (VBN ACCESS) 

The $WRITE macro calls the WRITE operation routine to write blocks to 
a file. The target of a VBN-access WRITE operation is the writable 
block (and, for a multiblock WRITE operation, following blocks). 



FORMAT 

The format for the $WRITE is: 

$WRITE rabaddr [ , [erraddr] [ , sucaddr] ] 

where rabaddr is the address of the RAB for the operation; erraddr is 
the address of the error handler for the operation; and sucaddr is 
the address of the success handler for the operation. 



CONTROL BLOCKS 

You must supply a RAB for the WRITE operation. 



OPTIONS 



Internal Stream Identifier 

The WRITE operation reads the internal stream identifier from the 
1-word ISI field of the RAB. 



Block Identification 

Specify the virtual block number of the first block to be written in 
the 2-word BKT field of the RAB. 



Record Buffer 

Specify the address of the record buffer in the 1-word RBF field of 
the RAB, and specify the size (in bytes) of the record buffer in the 
1-word RSZ field of the RAB. You must specify a record buffer for the 
WRITE operation; the WRITE operation transfers data from this buffer 
to the file. 

The WRITE operation normally updates the logical end-of-file marker, 
when appropriate, and automatically extends the file's allocation, 
when necessary. For sequential files with undefined (UDF) record 
format, however, the WRITE operation updates the logical end-of-file 
marker and performs automatic file extensions only if no wri te-shar ing 
has been specified in the 1-byte SHR field of the FAB. 



Asynchronous Operation 

If you want to execute the WRITE operation asynchronously, set the 
RB$ASY mask in the 1-word ROP field of the RAB; if you do not set 
this mask, the WRITE operation executes synchronously. (Your program 
must also have given the ASYN argument to the RAB$B macro that 
declared the RAB for the asynchronous operation.) 
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STREAM CONTEXT 

The readable-block context after a WRITE operation is the block 
following the last-written block; the writable-block context after a 
WRITE operation is the block following the last-written block. 



RETURNED VALUES 



Record File Address (RFA) 

The WRITE operation returns the virtual block number of the 
first-written block in the first two words of the 3-word RFA field of 
the RAB (it clears the third word) . 



Completion Status and Value 

The WRITE operation returns completion status in the 1-word STS field 
of the RAB and returns a completion value in the 1-word STV field of 
the RAB. Appendix A lists completion status symbols and values. 



CHECKLISTS 

Table 5-66 lists control block fields that are input to the WRITE 
operation. Table 5-67 lists control block fields that are output by 
the WRITE operation. 



Table 5-66: WRITE (VBN Access) Input Fields 



Block 


Field 


Description 


RAB 


BKT 


Virtual block number (VBN) 


RAB 


ISI 


Internal stream identifier 


RAB 


RBF 


Record buffer address 


RAB 


ROP 


Record processing option mask 






RB$ASY Asynchronous operation 


RAB 


RSZ 


Record size (bytes) 


Table 5-67: WRITE (VBN Access) Output Fields 


Block 


Field 


Description 


RAB 


RFA 


Virtual block number (2 words) 


RAB 


STS 


Completion status code 


RAB 


STV 


Completion status value 
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Each major section of this chapter describes an RMS-11 control block, 
and includes: 

• Block summary table 

A table summarizes the entire control block. The table shows 
the offset, offset symbol, field size, and a brief description 
of each field in the block; for each mask or code for a 
field, the table shows the value, symbol, and a brief 
description of the mask or code. 

• Field summaries 

Each subsection following the block summary table is a 
description of one field in the block. A field that has masks 
that are very different in purpose (such as the FOP field in 
the FAB) is described as a number of separate "fields" (such 
as FOP FB$FID, FOP FB$RWO, and so forth) . 

The description of each field includes the following: 

USE: a summary of the purpose of the field 

SIZE: the size of the field 

INIT: the format of the field-initialization macro (if any) 

ACCESS: the formats of field-access macros to access the 
field 

MASKS or CODES: (if any) each mask or code symbol and a brief 
description 

INPUT: the operations that read values from the field, and 
the meanings of those values 

OUTPUT: the operations that store values in the field, and 
the meanings of those values 

Fields described as "Reserved" and undefined bits in masks should (and 
in some cases must) be 0. 
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6.1 ALL BLOCK SUMMARY 

This section summarizes the ALL block and its fields. Table 6-1 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-1: ALL Block Summary 



Offset Field 
Offset Symbol Size Description 



000 0$COD 1 byte ALL block identifier code 

000004 XB$ALL ALL block identifier 



001 


0$BLN 


1 


byte 


ALL block length (bytes) 










000034 XB$LAL ALL block 


002 


0$NXT 


1 


word 


Next XAB address 


004 


0$AID 


1 


byte 


Area number 


005 


0$BKZ 


1 


byte 


Area bucket size (blocks) 


006 


0$VOL 


1 


word 


Reserved 


010 


0$ALN 


1 


byte 


Area alignment mask 



length (bytes) 



000002 XB$LBN Logical block alignment 
000004 XB$VBN Virtual block alignment 



011 


0$AOP 


1 


byte 


Area option mask 










000001 XB$HRD Hard area location 










000002 XB$CTG Contiguous area 


012 


0$ALQ 


2 


words 


Area allocation size (blocks) 


012 


O$ALQ0 


1 


word 


ALQ field low word 


014 


0$ALQ1 


1 


word 


ALQ field high word 


016 


0$DEQ 


1 


word 


Area default extension size (blocks) 


020 




1 


word 


Reserved 


022 


0$LOC 


2 


words 


Area location 


022 


O$LOC0 


1 


word 


LOC field low word 


024 


0$L0C1 


1 


word 


LOC field high word 
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6.1.1 AID Field in ALL Block 



USE 



Contains the area identifier for the area described by the 
ALL block. 



INIT 
SIZE 
ACCESS 

INPUT 



X$AID number 
1 byte 

$FETCH dst,AID f reg 
$STORE src,AID,reg 
$COMPARE src,AID,reg 



CLOSE 

CREATE 

DISPLAY 

EXTEND 

OPEN 



Area number 
Area number 
Area number 
Area number 
Area number 



AID field to 1-byte dst 
1-byte src to AID field 
1-byte src with AID field 



6-3 



CONTROL BLOCK FIELDS 
ALL BLOCK SUMMARY 



6.1.2 ALN Field in ALL Block 



USE 



Indicates alignment for the area described by the ALL 
block . 



INIT 
SIZE 
ACCESS 



MASKS 



INPUT 



OUTPUT 



X$ALN mask 
1 byte 

$SET mask, ALN, reg 
$OFF mask, ALN, reg 



;Mask bits on in ALN field 
;Mask bits off in ALN field 



$TESTB ITS mask, ALN, reg ;Test mask bits in ALN field 



$FETCH dst,ALN,reg 
$STORE src,ALN,reg 



; ALN field to 1-byte dst 
;l-byte src to ALN field 



$COMPARE src, ALN, reg ; 1-byte src with ALN field 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 

CREATE Initial area alignment request 

EXTEND Area extension alignment request 

DISPLAY Area alignment mask (cleared) 

OPEN Area alignment mask (cleared) 
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6.1.3 ALQ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Contains the allocation size for the area described by the 
ALL block. 

X$ALQ number 

2 words 



$FETCH dst,ALQ,reg 
$STORE src,ALQ,reg 
$FETCH dst,ALQn,reg 
$STORE src,ALQn,reg 
$COMPARE src,ALQn,reg 



; ALQ field to 2-word dst 
; 2-word src to ALQ field 
; ALQ word n to 1-word dst 
; 1-word src to ALQ word n 
; 1-word src with ALQ word n 



CREATE 
EXTEND 



CREATE 
DISPLAY 
EXTEND 
OPEN 



Initial area allocation request size (blocks) 
Area allocation extension request size 
(blocks) 



Initial area allocation size (blocks) 
Unused area allocation size (blocks) 
Area allocation extension actual size 
Unused area allocation size (blocks) 



(blocks) 
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6.1.4 AOP Field in ALL Block (XB$CTG Mask) 



USE 



Indicates contiguity for the area described by 
block . 



the ALL 



INIT X$AOP mask 

SIZE 1 byte 

ACCESS $SET mask, AOP, reg ;Mask bits on in AOP field 

$OFF mask, AOP, reg ;Mask bits off in AOP field 

$TESTB ITS mask, AOP, reg ;Test mask bits in AOP field 

$FETCH dst,AOP,reg ;AOP field to 1-byte dst 

$STORE src, AOP, reg ;l-byte src to AOP field 

^COMPARE src, AOP, reg ;l-byte src with AOP field 



INPUT 



OUTPUT 



CREATE Contiguous area request 

EXTEND Contiguous area extension request 

DISPLAY Contiguous area (cleared) 

OPEN Contiguous area (cleared) 
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6.1.5 AOP Field in ALL Block (XB$HRD Mask) 



USE Indicates a demand for the requested location. 

INIT X$AOP mask 

SIZE 1 byte 

ACCESS $SET mask, AOP, reg ;Mask bits on in AOP field 

$OFF mask, AOP, reg ;Mask bits off in AOP field 

$TESTBITS mask,AOP f reg ;Test mask bits in AOP field 

$FETCH dst,AOP,reg ;AOP field to 1-byte dst 

$STORE src, AOP, reg ;l-byte src to AOP field 

$COMPARE src, AOP, reg ; 1-byte src with AOP field 

INPUT CREATE Area hard location request 

EXTEND Area extension hard location request 

OUTPUT DISPLAY Hard area location (cleared) 

OPEN Hard area location (cleared) 
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6.1.6 BKZ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket size for the area described by the ALL 
block . 

X$BKZ number 
1 byte 

$FETCH dst,BKZ,reg ;BKZ field to 1-byte dst 

$STORE src,BKZ,reg ;l-byte src to BKZ field 

$COMPARE src,BKZ,reg ; 1-byte src with BKZ field 

CREATE Area bucket size (blocks) 

DISPLAY Area bucket size (blocks) 

OPEN Area bucket size (blocks) 
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6.1.7 BLN Field in ALL Block (XB$LAL Code) 

USE Contains the length of the ALL block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.1.8 COD Field in ALL Block (XB$ALL Code) 

USE Contains the identifier for the ALL block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ;l-byte src with COD field 
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6.1.9 DEQ Field in ALL Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the default extension size for the area described 
by the ALL block. 

X$DEQ number 

1 word 



$FETCH dst,DEQ,reg 
$STORE src,DEQ,reg 
$COMPARE src,DEQ,reg 



;DEQ field to 1-word dst 
;l-word src to DEQ field 
;l-word src with DEQ field 



CREATE Area default extension size (blocks) 

DISPLAY Area default extension size (blocks) 

OPEN Area default extension size (blocks) 
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6.1.10 LOC Field in ALL Block 



USE 



Contains the location of the area 
block . 



described by the ALL 



INIT 
SIZE 
ACCESS 



INPUT 



The meaning of the location depends on the ALN mask: a 
logical block number (if XB$LBN) or a virtual block number 
(if XB$VBN) . 

X$LOC number 

2 words 



$FETCH dst,LOC,reg 
$STORE src,LOC,reg 
$FETCH dst,LOCn,reg 
$STORE src,LOCn,reg 
$COMPARE src,LOCn,reg 



;LOC field to 2-word dst 
;2-word src to LOC field 
;L0C word n to 1-word dst 
; 1-word src to LOC word n 
; 1-word src with LOC word n 



CREATE Initial area location request 

EXTEND Area extension location request 
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6.1.11 

USE 

INIT 
SIZE 
ACCESS 

INPUT 



NXT Field in ALL Block 



Contains the address of the next XAB (ALL , DAT, KEY, PRO, 
or SUM block) in a chain of XABs . 



X$NXT address 



1 word 



$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



NXT field to 1-word dst 
1-word src to NXT field 
1-word src with NXT field 



CLOSE 


Next 


XAB 


address 


CREATE 


Next 


XAB 


address 


DISPLAY 


Next 


XAB 


address 


ENTER 


Next 


XAB 


address 


ERASE 


Next 


XAB 


address 


EXTEND 


Next 


XAB 


address 


OPEN 


Next 


XAB 


address 


PARSE 


Next 


XAB 


address 


REMOVE 


Next 


XAB 


address 


RENAME 


Next 


XAB 


address 


SEARCH 


Next 


XAB 


address 
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6.2 DAT BLOCK SUMMARY 

This section summarizes the DAT block and its fields. Table 6-2 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-2: DAT Block Summary 



Offset Field 
Offset Symbol Size Description 



000 


0$COD 


1 


byte 


DAT block identifier code 










000003 XB$DAT DAT block 


001 


0$BLN 


1 


byte 


DAT block length (bytes) 










000046 XB$DTL DAT block 


002 


0$NXT 


1 


word 


Next XAB address 


004 


0$RVN 


1 


word 


File revision number 


006 


0$RDT 


4 


words 


File revision date 


016 


0$CDT 


4 


words 


File creation date 


026 


0$EDT 


4 


words 


File expiration date 


036 


0$BDT 


4 


words 


Reserved 
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6.2.1 BLN Field in DAT Block (XB$DTL Code) 

USE Contains the length of the DAT block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ;l-byte src with BLN field 
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6.2.2 CDT Field in DAT Block 



USE 



Contains the binary creation date for the file. The time 
value is a binary number in 100-nanosecond units offset 
from the system base date and time, which is 00:00 
o'clock, November 17, 1858 (the Smithsonian base date and 
time for the astronomical calendar) . 



INIT 
SIZE 
ACCESS 
OUTPUT 



None 
4 words 

$FETCH dst,CDT,reg 



;CDT field to 4-word dst 



DISPLAY File creation date 

OPEN File creation date 
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6.2.3 COD Field in DAT Block (XB$DAT Code) 

USE Contains the identifier for the DAT block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ; 1-byte src with COD field 
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6.2.4 EDT Field in DAT Block 



USE 



INIT 
SIZE 
ACCESS 
OUTPUT 



Contains the expiration date for the file. The time value 
is a binary number in 100-nanosecond units offset from the 
system base date and time, which is 00:00 o'clock, 
November 17, 1858 (the Smithsonian base date and time for 
the astronomical calendar). 

None 



4 words 

$FETCH dst,EDT,reg 



; EDT field to 4-word dst 



OPEN File expiration date 

DISPLAY File expiration date 
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6.2.5 NXT Field in DAT Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the next XAB (ALL , DAT , KEY, 
or SUM block) in a chain of XABs . 

X$NXT address 

1 word 



PRO, 



$FETCH dst 


, NXT, reg 


;NXT 


$STORE src 


, NXT , reg 


; 1-wo 


$COMPARE src, NXT 


, reg 


; 1-wo 


CLOSE 


Next 


XAB 


address 


CREATE 


Next 


XAB 


address 


DISPLAY 


Next 


XAB 


address 


ENTER 


Next 


XAB 


address 


ERASE 


Next 


XAB 


address 


EXTEND 


Next 


XAB 


address 


OPEN 


Next 


XAB 


address 


PARSE 


Next 


XAB 


address 


REMOVE 


Next 


XAB 


address 


RENAME 


Next 


XAB 


address 


SEARCH 


Next 


XAB 


address 
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6.2.6 RDT Field in DAT Block 



USE 



INIT 
SIZE 
ACCESS 
OUTPUT 



Contains the binary revision date for the file. The time 
value is a binary number in 100-nanosecond units offset 
from the system base date and time, which is 00:00 
o'clock, November 17, 1858 (the Smithsonian base date and 
time for the astronomical calendar) . 



None 
4 words 

$FETCH dst,RDT,reg 



; RDT field to 4-word dst 



DISPLAY File revision date 

OPEN File revision date 
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6.2.7 RVN Field in DAT Block 

USE Contains the revision number (number of times closed) for 

the file. 

INIT None 

SIZE 1 word 

ACCESS $FETCH dst,RVN,reg ;RVN field to 1-word dst 

$COMPARE src,RVN,reg ;l-word src with RVN field 

OUTPUT DISPLAY File revision number 

OPEN File revision number 
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6.3 FAB SUMMARY 

This section summarizes the FAB and its fields. Table 6-3 summarizes 
the entire block, giving the offset, offset symbol, size, and a brief 
description for each field; for a field that has mask or code 
symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-3: FAB Summary 



Offset Field 
Offset Symbol Size Description 



000 


0$BID 


1 


byte 


FAB identifier 










000003 FB$B ID FAB identification code 


001 


0$BLN 


1 


byte 


FAB length (bytes) 










000120 FB$BLN FAB length (bytes) 


002 


0$CTX 


1 


word 


User context 


004 


0$IFI 


1 


word 


Internal file identifier 


006 


0$STS 


1 


word 


Completion status code 


010 


0$STV 


1 


word 


Completion status value 


012 


0$ALQ 


2 


words 


File allocation size (blocks) 


016 


0$DEQ 


1 


word 


File default extension size (blocks) 


020 


0$FAC 


1 


byte 


Requested access mask 



000001 FB$PUT Request put access 

000002 FB$GET Request find/get access 
000004 FB$DEL Request find/get/delete 

access 

000010 FB$UPD Request find/get/update 
access 

000020 FB$TRN Request find/get/truncate 
access 

000041 FB$WRT Request block write 

access 

000042 FB$REA Request block read access 



021 0$SHR 1 byte Shared access mask 



000002 FB$GET Share find/get access 
000015 FB$WRI Share find/get/put/update/ 

delete access 
000040 FB$UPI Share any access 

(user-provided interlock) 
000100 FB$NIL No access sharing 



(Continued on next page) 
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Table 6-3 (Cont.): FAB Summary 



Offset Field 
Offset Symbol Size Description 



022 0$FOP 1 word File processing option mask 

000001 FB$RWO Rewind magtape before 

operat i on 

000002 FB$RWC Rewind magtape after 

closing file 
000010 FB$POS Position magtape after 

last-closed file 
000020 FB$DLK No file locking on 

abnormal close 
000200 FB$CTG Contiguous file 
000400 FB$SUP Supersede existing file 
001000 FB$NEF No end-of-file magtape 

positioning 
002000 FB$TMP Temporary file 
004000 FB$MKD Mark file for deletion 
006000 FB$TMD Temporary file, mark for 

deletion 

010000 FB$F I D Use information in NAM 
block 

020000 FB$DFW Defer writing 

024 0$RTV 1 byte Retrieval pointer count 

025 0$ORG 1 byte File organization code 



000000 FB$SEQ Sequential file 

organi zat ion 
000020 FB$REL Relative file 

organ i zat i on 
000040 FB$IDX Indexed file organization 



026 0$RAT 1 byte Record handling mask 



000001 FB$FTN 



000002 FB$CR 



000004 
000010 



FB$ PRN 
FB$BLK 



FORTRAN-style 
carri age- control 
character in record 
Add CRLF to print record 
(LF-record-CR) 
VFC print record handling 
Blocked records 



027 0$RFM 1 byte Record format code 



000000 FB$UDF Undefined record format 

000001 FB$FIX Fixed-length record 

format 

000002 FB$VAR Variable-length record 

format 

000003 FB$VFC VFC record format 

000004 FB$STM Stream record format 



(Continued on next page) 
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Table 6-3 (Cont.): FAB Summary 



Offset Field 
Offset Symbol Size Description 



030 


0$XAB 


1 


word 


XAB address 


032 


0$BPA 


1 


word 


Private buffer pool address 


034 


0$BPS 


1 


wo rd 


Private buffer pool size (bytes 


036 


0$MRS 


1 


word 


Maximum record size (bytes) 


040 


0$MRN 


2 


words 


Maximum record number 


044 


0$LRL 


1 


word 


Longest record length 


046 


0$NAM 


1 


word 


NAM block address 


050 


0$FNA 


1 


word 


File string address 


052 


0$DNA 


1 


word 


Default string address 


054 


0$FNS 


1 


byte 


File string size (bytes) 


055 


0$DNS 


1 


byte 


Default string size (bytes) 


056 


0$BLS 


1 


word 


Magtape block size (characters) 


060 


0$FSZ 


1 


byte 


Fixed control area size for VFC 










(bytes ) 


061 


0$BKS 


1 


byte 


File bucket size (blocks) 


062 


0$DEV 


1 


byte 


Device characteristic mask 



000001 FB$REC Record-oriented device 

000002 FB$CCL Carriage-control device 
000004 FB$TRM Terminal device 
000010 FB$MDI Multidirectory device 
000020 FB$SDI Single-directory device 
000040 FB$SQD Sequential device 



063 0$LCH 1 byte Logical channel number 
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6.3.1 ALQ Field in FAB 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Contains the allocation size for the file. 
F$ALQ number 
2 words 



$FETCH dst 7 ALQ,reg 
$STORE src,ALQ,reg 
$FETCH dst,ALQn,reg 
$STORE src,ALQn,reg 
$COMPARE src,ALQn,reg 



ALQ field to 2-word dst 
2-word src to ALQ field 
ALQ word n to 1-word dst 
1-word src to ALQ word n 
1-word src with ALQ word 



CREATE 
EXTEND 



CREATE 
EXTEND 
OPEN 



Initial file allocation request size (blocks) 
File allocation extension request size 
(blocks) 

Initial file allocation size (blocks) 

File allocation extension actual size (blocks) 

Current file allocation (blocks) 
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6.3.2 BID Field in FAB (FB$BID Code) 

USE Contains the identifier for the FAB. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BID,reg ;BID field to 1-byte dst 

$COMPARE src,BID,reg ; 1-byte src with BID field 
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6.3.3 BKS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket size for the file. 
F$BKS number 
1 byte 



$FETCH dst,BKS,reg 
$STORE src,BKS,reg 
$COMPARE src,BKS,reg 



BKS field to 1-byte dst 
1-byte src to BKS field 
1-byte src with BKS field 



CREATE File bucket size (blocks) 

OPEN File bucket size (blocks) 
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6.3.4 BLN Field in FAB (FB$BLN Code) 

USE Contains the length of the FAB . 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ;l-byte src with BLN field 
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6.3.5 BLS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the magtape block size for the file. 
F$BLS number 



1 word 

$FETCH dst,BLS,reg 
$STORE src,BLS,reg 
$COMPARE src,BLS,reg 



;BLS field to 1-word dst 
;l-word src to BLS field 
;l-word src with BLS field 



CREATE Magtape block size (characters) 

OPEN Magtape block size (characters) 
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6.3.6 BPA Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the private buffer pool for the 
operat i on . 

F$BPA address 

1 word 



$FETCH dst,BPA,reg 
$STORE src,BPA,reg 
$COMPARE src,BPA,reg 



;BPA field to 1-word dst 
;l-word src to BPA field 
;l-word src with BPA field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Private 
Private 
Private 
Private 
Private 
Pr i vate 
Pr i vate 
Private 



buffer 
buffer 
buffer 
buffer 
buffer 
buffer 
buffer 
buffer 



pool 
pool 
pool 
pool 
pool 
pool 
pool 
pool 



address 
address 
address 
address 
address 
address 
address 
address 



OUTPUT 



CLOSE 



Private buffer pool address 
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6.3.7 BPS Field in FAB 



USE Contains the size of 

operation . 

INIT F$BPS number 

SIZE 1 word 

ACCESS $FETCH dst,BPS,reg 

$STORE src,BPS,reg 
$COMPARE src,BPS,reg 



the private buffer pool for the 



BPS field to 1-word dst 
1-word src to BPS field 
1-word src with BPS field 



INPUT 


CREATE 


Private 


buffer 


pool 


si ze 


(bytes ) 




ENTER 


Private 


buffer 


pool 


size 


(bytes) 




ERASE 


Pr i vate 


buffer 


pool 


size 


(bytes ) 




OPEN 


Pr i vate 


buffer 


pool 


size 


(bytes ) 




PARSE 


Pr i vate 


buffer 


pool 


size 


(bytes ) 




REMOVE 


Private 


buffer 


pool 


size 


(bytes) 




RENAME 


Private 


buffer 


pool 


si ze 


(bytes ) 




SEARCH 


Private 


buffer 


pool 


si ze 


(bytes ) 


OUTPUT 


CLOSE 


Private 


buffer 


pool 


si ze 


(bytes) 
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6.3.8 CTX Field in FAB 



USE 



Contains any information you may want to associate with 
the file at run time. 



INIT F$CTX number 

SIZE 1 word 

ACCESS $FETCH dst,CTX,reg 

$STORE src,CTX,reg 
$COMPARE src,CTX,reg 



CTX field to 1-word dst 
1-word src to CTX field 
1-word src with CTX field 
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6.3.9 DEQ Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the default extension size for the file. 
F$DEQ number 
1 word 



$FETCH dst,DEQ,reg 
$STORE src,DEQ,reg 
$COMPARE src f DEQ,reg 



;DEQ field to 1-word dst 
;l-word src to DEQ field 
;l-word src with DEQ field 



CREATE Permanent file default extension size (blocks) 

OPEN While-open file default extension size 

(blocks) 



OUTPUT 



OPEN 



Current file default extension size (blocks) 
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6.3.10 DEV Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

MASKS 



OUTPUT 



Indicates device characteristics for the file. 

None 

1 byte 

$TESTB ITS mask, DEV, reg ;Test mask bits in DEV field 
$FETCH dst,DEV,reg ;DEV field to 1-byte dst 

$COMPARE src,DEV,reg ;l-byte src with DEV field 

FB$CCL Carriage-control device 

FB$MDI Multidirectory device 

EB$REC Record-oriented device 

FB$SDI Single-directory device 

FB$SQD Sequential device 

FB$TRM Terminal device 

CREATE Device characteristic mask 

ENTER Device characteristic mask 

ERASE Device characteristic mask 

OPEN Device characteristic mask 

PARSE Device characteristic mask 

REMOVE Device characteristic mask 

RENAME Device characteristic mask 

SEARCH Device characteristic mask 
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6.3.11 DNA Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the default string for the 
operation . 

F$DNA address 

1 word 



$FETCH dst,DNA,reg 
$STORE src,DNA,reg 
$COMPARE src,DNA,reg 



;DNA field to 1-word dst 
; 1-word src to DNA field 
;l-word src with DNA field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Default 
Default 
Default 
Default 
Default 
Default 
Default 



string 
string 
string 
string 
string 
string 
string 



address 
address 
address 
address 
address 
address 
address 
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6.3.12 DNS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the default string for the operation 
F$DNS number 



1 byte 

$FETCH dst,DNS,reg 
$STORE src,DNS,reg 
$COMPARE src,DNS,reg 



;DNS field to 1-byte dst 
;l-byte src to DNS field 
; 1-byte src with DNS field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Default 
Default 
Default 
Default 
Default 
Default 
Default 



string size 
string size 
string size 
string size 
string size 
string size 
string size 



(bytes) 
(bytes ) 
(bytes) 
(bytes) 
(bytes ) 
(bytes ) 
(bytes ) 
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6.3.13 FAC Field in FAB 



USE 
INIT 
SIZE 
ACCESS 



MASKS 



INPUT 



Indicates the requested access for the file. 
F$FAC mask 



1 byte 

$SET mask, FAC, reg 
$OFF mask, FAC, reg 
$TESTBITS mask, FAC, reg 
$FETCH dst,FAC,reg 
$STORE src,FAC,reg 
$COMPARE src,FAC,reg 



;Mask bits on in FAC field 
;Mask bits off in FAC field 
;Test mask bits in FAC field 
;FAC field to 1-byte dst 
;l-byte src to FAC field 
; 1-byte src with FAC field 



FB$DEL Request find/get/delete access 

FB$GET Request find/get access 

FB$PUT Request put access 

FB$REA Request block read access 

FB$TRN Request find/get/truncate access 

FB$UPD Request find/get/update access 

FB$WRT Request block write access 

CREATE Requested access mask 

OPEN Requested access mask 
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6.3.14 FNA Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the file string for the file 
F$FNA address 
1 word 



$FETCH dst,FNA,reg 
$STORE src,FNA,reg 
$COMPARE src,FNA,reg 



;FNA field to 1-word dst 
; 1-word src to FNA field 
;l-word src with FNA field 

CREATE File string address 

ENTER File string address 

ERASE File string address 

OPEN File string address 

PARSE File string address 

REMOVE File string address 

RENAME File string address 
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6.3.15 

USE 
INIT 
SIZE 
ACCESS 

INPUT 



FNS Field in FAB 



Contains the size of the file string for the file 
F$FNS number 
1 byte 



$FETCH dst,FNS,reg 
$STORE src,FNS,reg 
$COMPARE src,FNS,reg 



;FNS field to 1-byte dst 
;l-byte src to FNS field 
; 1-byte src with FNS field 



CREATE File string size (bytes) 

ENTER File string size (bytes) 

ERASE File string size (bytes) 

OPEN File string size (bytes) 

PARSE File string size (bytes) 

REMOVE File string size (bytes) 

RENAME File string size (bytes) 
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6.3.16 FOP Field in FAB (FB$CTG Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Indicates file contiguity. 
F$FOP mask 
1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

CREATE Contiguous file request 

EXTEND Contiguous file extension request 



OUTPUT 



OPEN 



Contiguous file 
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6.3.17 FOP Field in FAB (FB$DFW Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests deferred writing for the file. 
F$FOP mask 



1 word 

$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTBITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



CREATE Defer writing 

OPEN Defer writing 
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6.3.18 FOP Field in FAB (FB$DLK Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests no file locking if the file is closed abnormally 
F$FOP mask 
1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTB ITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

CREATE No file locking on abnormal close 

OPEN No file locking on abnormal close 
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6.3.19 

USE 

INIT 
SIZE 
ACCESS 

INPUT 



FOP Field in FAB (FB$FID Mask) 



Requests that NAM block information be used to identify 
the file. 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

CREATE Use information in NAM block 

ENTER Use information in NAM block 

ERASE Use information in NAM block 

OPEN Use information in NAM block 

REMOVE Use information in NAM block 

RENAME Use information in NAM block 
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6.3.20 FOP Field in FAB (FB$MKD Mask) 



OSE 
INIT 
SIZE 
ACCESS 



Requests that the file be marked for deletion. 
F$FOP mask 
1 word 



$SET mask, FOP, reg 
$OFF mask,FOP,reg 
$TESTB ITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src, FOP, reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



INPUT 



CREATE 



Mark file for deletion 
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6.3.21 

USE 

INIT 
SIZE 
ACCESS 

INPUT 



FOP Field in FAB (FB$NEF Mask) 



Requests that the magtape file be positioned to the 
beginning of the file. 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

OPEN No end-of-file magtape positioning 
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6.3.22 FOP Field in FAB (FB$POS Mask) 



USE 

INIT 
SIZE 
ACCESS 



Requests that the magtape be positioned to the end of 
last-closed file before creating the new file. 

F$FOP mask 

1 word 



the 



$SET mask, FOP, reg 
$OFF mask, FOP, reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 



$TESTB ITS mask, FOP, reg ;Test mask bits in FOP field 



$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;FOP field to 1-word dst 
;l-word src to FOP field 
;l-word src with FOP field 



INPUT 



CREATE 



Position magtape after last-closed file 
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6.3.23 

USE 

INIT 
SIZE 
ACCESS 

INPUT 



FOP Field in FAB (FB$RWC Mask) 



Requests that the magtape be rewound when the file is 
closed . 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTBITS mask, FOP, reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ;l-word src to FOP field 

$COMPARE src, FOP, reg ; 1-word src with FOP field 

CLOSE Rewind magtape after closing file 

CREATE Rewind magtape after closing file 

OPEN Rewind magtape after closing file 

SEARCH Rewind magtape after closing file 
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6.3.24 FOP Field in FAB (FB$RWO Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests that the magtape be rewound before the operation 
F$FOP mask 



1 word 

$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTB ITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



CREATE 

OPEN 

SEARCH 



Rewind magtape before creating file 
Rewind magtape before searching for file 
Rewind magtape before operation 
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6.3.25 

USE 

INIT 
SIZE 
ACCESS 

INPUT 



FOP Field in FAB (FB$SUP Mask) 



Requests that the created file supersede the old file with 
the same specification (if one exists). 

F$FOP mask 

1 word 

$SET mask, FOP, reg ;Mask bits on in FOP field 

$OFF mask, FOP, reg ;Mask bits off in FOP field 

$TESTB ITS mask,FOP,reg ;Test mask bits in FOP field 

$FETCH dst,FOP,reg ;FOP field to 1-word dst 

$STORE src,FOP,reg ; 1-word src to FOP field 

$COMPARE src, FOP, reg ;l-word src with FOP field 

CREATE Supersede existing file 
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6.3.26 FOP Field in FAB (FB$TMP Mask) 



USE 

INIT 
SIZE 
ACCESS 



Requests that the created file be a temporary file (one 
with no directory entry). 

F$FOP mask 

1 word 



$SET mask, FOP, reg 
$OFF mask, FOP, reg 
$TESTBITS mask, FOP, reg 
$FETCH dst,FOP,reg 
$STORE src,FOP,reg 
$COMPARE src,FOP,reg 



;Mask bits on in FOP field 
;Mask bits off in FOP field 
;Test mask bits in FOP field 
;FOP field to 1-word dst 
; 1-word src to FOP field 
;l-word src with FOP field 



INPUT 



CREATE 



Temporary file 
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6.3.27 FSZ Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the size of the fixed control area for VFC 
records . 

F$FSZ number 

1 byte 



$FETCH dst,FSZ,reg 
$STORE src,FSZ,reg 
$COMPARE src,FSZ,reg 



;FSZ field to 1-byte dst 
;l-byte src to FSZ field 
;l-byte src with FSZ field 



CREATE 



OPEN 



Fixed control area size for VFC 
(bytes) 

Fixed control area size for VFC 
(bytes) 



records 
records 
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6.3.28 IFI Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the internal file identifier for the file 
None 



1 word 

$FETCH dst,IFI,reg 
$COMPARE src,IFI,reg 



CLOSE 
CONNECT 
DISPLAY 
EXTEND 

CLOSE 

CREATE 

OPEN 



Internal 
Internal 
Internal 
Internal 

Internal 
Internal 
Internal 



;IFI field to 1-word dst 
;l-word src with IFI field 



file 
file 
file 
file 

file 
file 
file 



ident i f ier 
identifier 
ident i f ier 
identifier 

identifier 
ident i f ier 
ident i f ier 
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6.3.29 LCH Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the logical channel number for the operation 
F$LCH number 



1 byte 

$FETCH dst,LCH,reg 
$STORE src,LCH,reg 
$COMPARE src,LCH,reg 



;LCH field to 1-byte dst 
;l-byte src to LCH field 
;l-byte src with LCH field 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Logical 
Logical 
Logical 
Logical 
Logical 
Logical 
Logical 
Logical 



channel 
channel 
channel 
channel 
channel 
channel 
channel 
channel 



number 
number 
number 
number 
number 
number 
number 
number 
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Contains the length of the longest record in a sequential 
file. 

None 

1 word 

$FETCH dst,LRL,reg ; LRL field to 1-word dst 

$COMPARE src,LRL,reg ; 1-word src with LRL field 



CONTROL BLOCK FIELDS 
FAB SUMMARY 

6.3.30 LRL Field in FAB 

USE 

INIT 
SIZE 
ACCESS 

INPUT CREATE 
OUTPUT OPEN 



Longest record length 
sequential files only) 

Longest record length 



(block access to 
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6.3.31 

USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



MRN Field in FAB 



Contains the maximum record number allowed in a 
file. 

F$MRN number 
2 words 



$FETCH dst,MRN,reg 
$STORE src,MRN,reg 
$FETCH dst,MRNn,reg 
$STORE src,MRNn,reg 
$COMPARE src,MRNn,reg 



;MRN field to 2-word dst 
; 2-word src to MRN field 
; MRN word n to 1-word dst 
; 1-word src to MRN word n 
; 1-word src with MRN word n 



CREATE Maximum record number 

OPEN Maximum record number 



6-55 



CONTROL BLOCK FIELDS 
FAB SUMMARY 



6.3.32 MRS Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the record size for fixed-length records or 
maximum record size for other format records for the file. 

F$MRS number 

1 word 



$FETCH dst,MRS,reg 
$STORE src,MRS,reg 
$COMPARE src,MRS,reg 



MRS field to 1-word dst 
1-word src to MRS field 
1-word src with MRS field 



CREATE Maximum record size (bytes) 

OPEN Maximum record size (bytes) 
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6.3.33 NAM Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the NAM block for the operation 
F$NAM address 
1 word 



$FETCH dst,NAM,reg 
$STORE src,NAM,reg 
$COMPARE src,NAM,reg 



; NAM field to 1-word dst 
; 1-word src to NAM field 
;l-word src with NAM field 



CREATE 


NAM 


block 


address 


ENTER 


NAM 


block 


address 


ERASE 


NAM 


block 


address 


OPEN 


NAM 


block 


address 


PARSE 


NAM 


block 


address 


REMOVE 


NAM 


block 


address 


RENAME 


NAM 


block 


address 


SEARCH 


NAM 


block 


address 
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6.3.34 ORG Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

CODES 

INPUT 
OUTPUT 



Contains the file organization code. 
F$ORG code 



1 byte 

$FETCH dst,ORG,reg 
$STORE src,ORG,reg 
$COMPARE src,ORG,reg 



ORG field to 1-byte dst 
1-byte src to ORG field 
1-byte src with ORG field 



FB$IDX Indexed file organization 

FB$REL Relative file organization 

FB$SEQ Sequential file organization 

CREATE File organization code 

OPEN File organization code 
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6.3.35 RAT Field in FAB 



USE 

INIT 
SIZE 
ACCESS 



MASKS 

INPUT 
OUTPUT 



Indicates the record-output characteristic for the file. 
(The RAT field also contains the record-blocking 
characteristic, which is described in the next section.) 

F$RAT mask 

1 byte 

$SET mask, RAT, reg ;Mask bits on in RAT field 

$OFF mask, RAT, reg ;Mask bits off in RAT field 

$TESTBITS mask,RAT,reg ;Test mask bits in RAT field 

$FETCH dst,RAT,reg ; RAT field to 1-byte dst 

$STORE src,RAT,reg ; 1-byte src to RAT field 

$COMPARE src, RAT, reg ;l-byte src with RAT field 

FB$CR Add CRLF to print record (LF-record-CR) 

FB$FTN FORTRAN-style carriage-control character in record 

FB$PRN VFC print record handling 



CREATE 



OPEN 



Record handling mask 
Record handling mask 
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6.3.36 RAT Field in FAB (FB$BLK Mask) 



USE 



Indicates whether the file has blocked records. (The RAT 
field also contains the record-output characteristic, 
which is described in the previous section.) 



INIT F$RAT mask 

SIZE 1 byte 

ACCESS $SET mask, RAT, reg ;Mask bits on in RAT field 

$OFF mask, RAT, reg ;Mask bits off in RAT field 

$TESTB ITS mask, RAT, reg ;Test mask bits in RAT field 



$FETCH dst,RAT,reg 
$STORE src,RAT,reg 
$COMPARE src,RAT,reg 



; RAT field to 1-byte dst 
;l-byte src to RAT field 
; 1-byte src with RAT field 



INPUT 
OUTPUT 



CREATE 



OPEN 



Blocked records 



Blocked records 
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6.3.37 RFM Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

CODES 



INPUT 
OUTPUT 



Contains the record format code for the file. 
F$RFM code 



1 byte 

$FETCH dst,RFM,reg 
$STORE src,RFM,reg 
$COMPARE src,RFM,reg 



; RFM field to 1-byte dst 
;l-byte src to RFM field 
; 1-byte src with RFM field 



FB$FIX Fixed-length record format 

FB$STM Stream record format 

FB$UDF Undefined record format 

FB$VAR Variable-length record format 

FB$VFC VFC record format 

CREATE Record format code 

OPEN Record format code 
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6.3.38 RTV Field in FAB 



OSE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the retrieval pointer count for the file 
F$RTV number 



1 byte 

$FETCH dst,RTV,reg 
$STORE src,RTV,reg 
$COMPARE src,RTV,reg 



;RTV field to 1-byte dst 
;l-byte src to RTV field 
;l-byte src with RTV field 



CREATE Retrieval pointer count 

OPEN Retrieval pointer count 
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6.3.39 SHR Field in FAB 



USE 
INIT 
SIZE 
ACCESS 



MASKS 



INPUT 



Indicates requested access sharing for the file. 
F$SHR mask 



1 byte 

$SET mask, SHR, reg 
$OFF mask, SHR, reg 
$TESTB ITS mask, SHR, reg 
$FETCH dst,SHR,reg 
$STORE src,SHR,reg 
$COMPARE src,SHR,reg 



;Mask bits on in SHR field 
;Mask bits off in SHR field 
;Test mask bits in SHR field 
;SHR field to 1-byte dst 
;l-byte src to SHR field 
; 1-byte src with SHR field 



FB$GET Share find/get access 

FB$NIL No access sharing 

FB$UPI Share any access (user-provided interlock) 

FB$WRI Share find/get/put/update/delete access 



CREATE 
OPEN 



Shared access mask 
Shared access mask 
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6.3.40 STS Field in FAB 



USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the completion status code for the operation 
None 



1 word 

$FETCH dst,STS,reg 
$COMPARE src,STS,reg 



;STS field to 1-word dst 
;l-word src with STS field 



CLOSE 

CREATE 

DISPLAY 

ENTER 

ERASE 

EXTEND 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Compl 
Compl 
Compl 
Compl 
Compl 
Compl 
Compl 
Compl 
Compl 
Compl 
Compl 



etion 
et i on 
etion 
etion 
etion 
etion 
etion 
et i on 
et ion 
etion 
etion 



status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 



code 
code 
code 
code 
code 
code 
code 
code 
code 
code 
code 
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6.3.41 

USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



STV Field in FAB 



Contains the completion status value for the operation. 



None 



1 word 



$FETCH dst,STV,reg ;STV field to 1-word dst 

$COMPARE src,STV,reg ;l-word src with STV field 



CLOSE 


Completion 


status 


value 


CREATE 


Complet i on 


status 


value 


DISPLAY 


Completion 


status 


value 


ENTER 


Completion 


status 


value 


ERASE 


Completion 


status 


value 


EXTEND 


Completion 


status 


value 


OPEN 


Completion 


status 


value 


PARSE 


Completion 


status 


value 


REMOVE 


Complet i on 


status 


value 


RENAME 


Completion 


status 


value 


SEARCH 


Complet i on 


status 


value 
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6.3.42 XAB Field in FAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the first XAB (ALL, DAT, KEY, PRO, 
or SUM block) in a chain of XABs . 

F$XAB address 

1 word 



$FETCH dst,XAB,reg 
$STORE src,XAB,reg 
$COMPARE src,XAB,reg 



XAB field to 1-word dst 
1-word src to XAB field 
1-word src with XAB field 



CLOSE 

CREATE 

DISPLAY 

EXTEND 

OPEN 



XAB address 
XAB address 
XAB address 
XAB address 
XAB address 
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6.4 KEY BLOCK SUMMARY 

This section summarizes the KEY block and its fields. Table 6-4 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-4: KEY Block Summary 



Offset Field 
Offset Symbol Size Description 



000 


0$COD 


1 


byte 


KEY block identifier code 










000001 XB$KEY KEY block identifier 


001 


0$BLN 


1 


byte 


KEY block length (bytes) 










000070 XB$KYL KEY block length (bytes) 


00 2 


0$NXT 


1 


word 


Next XAB address 


004 


0$REF 


1 


byte 


Index reference number 


005 


0$LVL 


1 


byte 


Number of index levels (not including 










data level) 


006 


0$IFL 


1 


word 


Index bucket fill factor 


010 


0$DFL 


1 


word 


Data bucket fill factor 


012 


0$NUL 


1 


byte 


Null key character 


013 


0$IAN 


1 


byte 


Higher level index area number 


014 


0$LAN 


1 


byte 


Lowest index level area number 


015 


0$DAN 


1 


byte 


Data area number 


016 


0$FLG 


1 


byte 


Index option mask 



000001 XB$DUP 

000002 XB$CHG 
000020 XB$INI 
000004 XB$NUL 



Duplicate record keys 
allowed 

Record key changes 

allowed on update 

No entries yet made in 

index 

Null record keys not 
indexed 



017 0$DTP 1 byte Key data type code 



000000 XB$STG String 

000001 XB$IN2 15-bit signed integer 

000002 XB$BN2 16-bit unsigned integer 

000003 XB$IN4 31-bit signed integer 

000004 XB$BN4 32-bit unsigned integer 

000005 XB$PAC Packed decimal number 



(Continued on next page) 
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Offset Field 
Offset Symbol Size Description 



020 


0$KNM 


1 


word 


Key 


name buffer address 


022 


0$POS 


8 


words 


Key 


segment 


pos i t ions 


022 


O$POS0 


1 


word 


Key 


segment 


position 


024 


0$POSl 


1 


word 


Key 


segment 


1 position 


026 


0$POS2 


1 


word 


Key 


segment 


2 position 


030 


0$POS3 


1 


word 


Key 


segment 


3 pos i t i on 


032 


0$POS4 


1 


word 


Key 


segment 


4 pos i t i on 


034 


0$POS5 


1 


word 


Key 


segment 


5 position 


036 


0$POS6 


1 


word 


Key 


segment 


6 position 


040 


0$POS7 


1 


word 


Key 


segment 


7 position 


042 


0$SIZ 


8 


bytes 


Key 


segment 


sizes (bytes) 


042 


O$SIZ0 


1 


byte 


Key 


segment 


size (bytes) 


043 


0$SIZ1 


1 


byte 


Key 


segment 


1 size (bytes) 


044 


0$SIZ2 


1 


byte 


Key 


segment 


2 size (bytes) 


045 


0$SIZ3 


1 


byte 


Key 


segment 


3 size (bytes) 


046 


0$SIZ4 


1 


byte 


Key 


segment 


4 size (bytes) 


047 


0$SIZ5 


1 


byte 


Key 


segment 


5 size (bytes) 


050 


0$SIZ6 


1 


byte 


Key 


segment 


6 size (bytes) 


051 


0$SIZ7 


1 


byte 


Key 


segment 


7 size (bytes) 


052 


0$RVB 


2 


words 


Root 


index 


bucket virtual block number 


056 


0$DVB 


2 


words 


First data 


bucket virtual block number 


062 


0$IBS 


1 


byte 


Index area 


bucket size (blocks) 


063 


0$DBS 


1 


byte 


Data 


area bucket size (blocks) 


064 


0$NSG 


1 


byte 


Key 


segment 


count 


065 


0$TKS 


1 


byte 


Total key size (sum of key segment sizes) 










(bytes ) 




066 


0$MRL 


1 


word 


Minimum length of record containing key 



(bytes) 
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6.4.1 BLN Field in KEY Block (XB$KYL Code) 

USE Contains the length of the KEY block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.4.2 COD Field in KEY Block (XB$KEY Code) 

USE Contains the identifier for the KEY block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$ COM PA RE src,COD,reg ;l-byte src with COD field 



6-70 



CONTROL BLOCK FIELDS 
KEY BLOCK SUMMARY 



6.4.3 DAN Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the area number of the data area 
described by the KEY block. 

X$DAN number 



for the index 



1 byte 

$FETCH dst,DAN,reg 
$STORE src,DAN f reg 
$COMPARE src,DAN,reg 



;DAN field to 1-byte dst 
;l-byte src to DAN field 
;l-byte src with DAN field 



CREATE Data area number 

DISPLAY Data area number 

OPEN Data area number 
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6.4.4 DBS Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the bucket size for the data area for 
described by the KEY block. 

None 



the index 



1 byte 

$FETCH dst,DBS,reg 
$COMPARE src,DBS,reg 



;DBS field to 1-byte dst 
;l-byte src with DBS field 



DISPLAY Data area bucket size (blocks) 

OPEN Data area bucket size (blocks) 
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6.4.5 DFL Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket fill number for the data area for the 
index described by the KEY block. 

X$DFL number 

1 word 



$FETCH dst,DFL,reg 
$STORE src,DFL,reg 
$COMPARE src,DFL,reg 



;DFL field to 1-word dst 
;l-word src to DFL field 
;l-word src with DFL field 



CREATE Data bucket fill factor 

DISPLAY Data bucket fill factor 

OPEN Data bucket fill factor 
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6.4.6 DTP Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

CODES 



INPUT 
OUTPUT 



Contains the key data type code for the index described by 
the KEY block. 

X$DTP code 

1 byte 



$FETCH dst,DTP,reg 
$STORE src,DTP,reg 
$COMPARE src,DTP,reg 



;DTP field to 1-byte dst 
;l-byte src to DTP field 
;l-byte src with DTP field 



XB$BN2 16-bit unsigned integer 

XB$BN4 32-bit unsigned integer 

XB$IN2 15-bit signed integer 

XB$IN4 31-bit signed integer 

XB$PAC Packed decimal number 

XB$STG String 

CREATE Key data type code 

DISPLAY Key data type code 

OPEN Key data type code 
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6.4.7 DVB Field in KEY Block 

USE Contains the virtual block number of the first bucket in 

the data area for the index described by the KEY block. 

INIT None 

SIZE 2 words 

ACCESS $FETCH dst,DVB,reg ;DVB field to 2-word dst 

OUTPUT DISPLAY First data bucket virtual block number 

OPEN First data bucket virtual block number 
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6.4.8 FLG Field in KEY Block (XB$CHG Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Specifies that a record key (for an alternate 
allowed to change when the record is updated. 

X$FLG mask 



index) is 



1 byte 

$SET mask, FLG, reg 
$OFF mask ,FLG,reg 
$TESTBITS mask, FLG, reg ;Test mask bits in FLG field 



;Mask bits on in FLG field 
;Mask bits off in FLG field 



$FETCH dst,FLG,reg 
$STORE src,FLG,reg 
$COMPARE src,FLG,reg 



; FLG field to 1-byte dst 
;l-byte src to FLG field 
;l-byte src with FLG field 



CREATE Record key changes allowed on update 

DISPLAY Record key changes allowed on update 

OPEN Record key changes allowed on update 
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6.4„9 FLG Field in KEY Block (XB$DUP Mask) 



USE 



Indicates that duplicate record keys are allowed for the 
index described by the KEY block; duplicate record keys 
are not allowed in the primary index. 



INIT X$FLG mask 

SIZE 1 byte 

ACCESS $SET mask, FLG, reg ;Mask bits on in FLG field 

$OFF mask, FLG, reg ;Mask bits off in FLG field 

$TESTBITS mask, FLG, reg ;Test mask bits in FLG field 



$FETCH dst,FLG,reg 
$STORE src,FLG,reg 
$COMPARE src,FLG,reg 



; FLG field to 1-byte dst 
;l-byte src to FLG field 
;l-byte src with FLG field 



INPUT CREATE Duplicate record keys allowed 

OUTPUT DISPLAY Duplicate record keys allowed 

OPEN Duplicate record keys allowed 
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6.4.10 FLG Field in KEY Block (XB$NUL Mask) 



USE 

INIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Indicates that records containing only null characters are 

not contained in the index described by the KEY block. 

(The null character is specified in the NUL field of the 
KEY block.) 

X$FLG mask 



1 byte 

$SET mask, FLG, reg 
$OFF mask, FLG, reg 
$TESTB ITS mask, FLG, reg 
$FETCH dst,FLG,reg 
$STORE src,FLG,reg 
$COMPARE src,FLG,reg 



Mask bits on in FLG field 
Mask bits off in FLG field 
Test mask bits in FLG field 
FLG field to 1-byte dst 
1-byte src to FLG field 
1-byte src with FLG field 



CREATE Null record keys not indexed 

DISPLAY Null record keys not indexed 

OPEN Null record keys not indexed 



6-78 



CONTROL BLOCK FIELDS 
KEY BLOCK SUMMARY 



6.4,. 11 IAN Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the area number of the area containing the higher 
index levels (all except the lowest level) for the index 
described by the KEY block. 

X$IAN number 



1 byte 

$FETCH dst,IAN,reg 
$STORE src,IAN,reg 
$COMPARE src,IAN,reg 



;IAN field to 1-byte dst 
;l-byte src to IAN field 
;l-byte src with IAN field 



CREATE Higher level index area number 

DISPLAY Higher level index area number 

OPEN Higher level index area number 
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6.4.12 IBS Field in KEY Block 

USE Contains the bucket size of the area containing the index 

described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,IBS,reg ;IBS field to 1-byte dst 

$COMPARE src,IBS,reg ;l-byte src with IBS field 

OUTPUT DISPLAY Index area bucket size (blocks) 

OPEN Index area bucket size (blocks) 
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6.4.13 IFL Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the bucket fill number for the 
the index described by the KEY block. 

X$IFL number 

1 word 



area containing 



$FETCH dst,IFL,reg 
$STORE src,IFL,reg 
$COMPARE src,IFL,reg 



;IFL field to 1-word dst 
;l-word src to IFL field 
;l-word src with IFL field 



CREATE Index bucket fill factor 

DISPLAY Index bucket fill factor 

OPEN Index bucket fill factor 
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6.4.14 KNM Field in KEY Block 



USE Contains the address of the 32-byte key name buffer for 

the index described by the KEY block. 

INIT X$KNM address 

SIZE 1 word 

ACCESS $FETCH dst,KNM,reg ; KNM field to 1-word dst 

$STORE src,KNM,reg ;l-word src to KNM field 

$COMPARE src,KNM,reg ;l-word src with KNM field 

INPUT CREATE Key name buffer address 

DISPLAY Key name buffer address 

OPEN Key name buffer address 
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6.4.15 

USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



LAN Field in KEY Block 



Contains the area number of the area containing the lowest 
level of the index described by the KEY block. 

X$LAN number 

1 byte 

$FETCH dst,LAN,reg ; LAN field to 1-byte dst 

$STORE src,LAN,reg ; 1-byte src to LAN field 

$COMPARE src,LAN,reg ;l-byte src with LAN field 

CREATE Lowest index level area number 

DISPLAY Lowest index level area number 

OPEN Lowest index level area number 
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6.4.16 LVL Field in KEY Block 



USE Contains the number of levels (not including the data 

level) for the index described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,LVL,reg ;LVL field to 1-byte dst 

$COMPARE src,LVL,reg ; 1-byte src with LVL field 

OUTPUT DISPLAY Number of index levels (not including data 

level) 

OPEN Number of index levels (not including data 

level ) 
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6.4.17 

USE 

INIT 
SIZE 
ACCESS 

OUTPUT 



MRL Field in KEY Block 



Contains the length of the smallest record that is long 
enough to completely contain a record key for the index 
described by the KEY block. 

None 

1 word 

$FETCH dst,MRL,reg ;MRL field to 1-word dst 

$COMPARE src,MRL,reg ; 1-word src with MRL field 

DISPLAY Minimum length of record containing key 

(bytes) 

OPEN Minimum length of record containing key 

(bytes) 
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6.4.18 NSG Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the number of key segments in 
index described by the KEY block. 

None 



the key for the 



1 byte 

$FETCH dst,NSG,reg 
$COMPARE src,NSG,reg 



;NSG field to 1-byte dst 
;l-byte src with NSG field 



DISPLAY Key segment count 

OPEN Key segment count 
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6.4.19 NUL Field in KEY Block 



USE 



Contains the null character for the (alternate) index 
described by the KEY block. For a string key (XB$STG in 
the DTP field of the KEY block) , the NUL field contains an 
ASCII character; for any other key data type, the NUL 
field is unused (nonstring keys use as the null value 
when the XB$NUL mask is set) . 



INIT X$NUL number 

SIZE 1 byte 

ACCESS $FETCH dst,NUL,reg 

$STORE src,NUL,reg 
^COMPARE src,NUL,reg 



;NUL field to 1-byte dst 
;l-byte src to NUL field 
; 1-byte src with NUL field 



INPUT CREATE Null key character 

OUTPUT DISPLAY Null key character 

OPEN Null key character 
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6.4.20 NXT Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs . 

X$NXT address 

1 word 



PRO, 



$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



NXT field to 1-word dst 
1-word src to NXT field 
1-word src with NXT field 



CLOSE 

CREATE 

DISPLAY 

ENTER 

ERASE 

EXTEND 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 



XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 



address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
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6.4.21 POS Field in KEY Block 



USE 

INIT 
SIZE 
ACCESS 



Contains the positions of segments for the record keys in 
the index described by the KEY block. (The first key 
position is position 0.) 

X$POS <number [ , number ] . . . > 

8 words 



$FETCH dst,POS,reg 
$STORE src,POS,reg 
$FETCH dst,POSn,reg 
$STORE src,POSn,reg 
$COMPARE src,POSn,reg 



POS field to 8-word dst 
8-word src to POS field 
POS word n to 1-word dst 
1-word src to POS word n 
1-word src with POS word n 



INPUT CREATE Key segment positions 

OUTPUT DISPLAY Key segment positions 

OPEN Key segment positions 
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6.4.22 REF Field in KEY Block 



USE 



Contains the reference number for the index 
the KEY block. 



described by 



INIT 
SIZE 
ACCESS 

INPUT 



X$REF number 
1 byte 

$FETCH dst,REF,reg 
$STORE src,REF,reg 
$COMPARE src,REF,reg 



REF field to 1-byte dst 
1-byte src to REF field 
1-byte src with REF field 



CLOSE Index reference number 

CREATE Index reference number 

DISPLAY Index reference number 

EXTEND Index reference number 

OPEN Index reference number 
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6.4.23 RVB Field in KEY Block 

USE Contains the virtual block number of the first block of 

the root bucket of the index described by the KEY block. 

INIT None 

SIZE 2 words 

ACCESS $FETCH dst,RVB,reg ;RVB field to 2-word dst 

OUTPUT DISPLAY Root index bucket virtual block number 

OPEN Root index bucket virtual block number 
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6.4.24 SIZ Field in KEY Block 



USE 

I NIT 
SIZE 
ACCESS 



INPUT 
OUTPUT 



Contains the sizes of segments for the record keys in 
index described by the KEY block. 

X$SIZ <number [ , number ]... > 



the 



8 bytes 

$FETCH dst,SIZ,reg 
$STORE src,SIZ,reg 
$FETCH dst,SIZn,reg 
$STORE src,SIZn,reg 
$COMPARE src,SIZn,reg 



SIZ field to 8-byte dst 
8-byte src to SIZ field 
SIZ byte n to 1-byte dst 
1-byte src to SIZ byte n 
1-byte src with SIZ byte n 



CREATE Key segment sizes (bytes) 

DISPLAY Key segment sizes (bytes) 

OPEN Key segment sizes (bytes) 
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6.4.25 TKS Field in KEY Block 



USE Contains the total key size (sum of the segment sizes) of 

a record key for the index described by the KEY block. 

INIT None 

SIZE 1 byte 

ACCESS $FETCH dst,TKS,reg ;TKS field to 1-byte dst 

$COMPARE src,TKS,reg ; 1-byte src with TKS field 

OUTPUT DISPLAY Total key size (sum of key segment sizes) 

(bytes) 

OPEN Total key size (sum of key segment sizes) 

(bytes) 
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6.5 NAM BLOCK SUMMARY 

This section summarizes the NAM block and its fields. Table 6-5 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-5: NAM Block Summary 



Offset Field 
Offset Symbol Size Description 



000 


0$RLF 


1 


word 


Reserved 


002 


0$RSA 


1 


word 


Resultant string buffer address 


004 


0$RSS 


1 


byte 


Resultant string buffer size (bytes) 


005 


0$RSL 


1 


byte 


Resultant string length (bytes) 


006 


0$DVI 


2 


words 


Device identifier 


012 


0$WDI 


1 


word 


Wildcard directory context 


014 


0$FID 


3 


words 


File identifier 


022 


0$DID 


3 


words 


Directory identifier 


030 


0$FNB 


1 


word 


File specification mask 



000001 NB$VER File version in file 

string or default string 

000002 NB$TYP File type in file string 

or default string 
000004 NB$NAM File name in file string 

or default string 
000010 NB$WVE Wildcard file version in 

file string or default 

string 

000020 NB$WTY Wildcard file type in 
file string or default 
string 

000040 NB$WNA Wildcard file name in 
file string or default 
string 

000100 NB$DIR Directory in file string 

or default string 
000200 NB$DEV Device in file string or 

default string 
000400 NB$NOD Node in file string or 

default string 
001000 NB$WDI Wildcard directory in 

file string or default 

string 

002000 NB$QUO Quoted string in file 

string or default string 

004000 NB$WCH Wildcard context 
es tabl i shed 



032 


0$ESA 1 


word 


Expanded 


string buffer 


address 


034 


0$ESS 1 


byte 


Expanded 


string buffer 


size (bytes) 


035 


0$ESL 1 


byte 


Expanded 


string length 


(bytes) 


036 


0$WCC 1 


word 


Wi ldcard 


context 





The first word of the NAM block is currently reserved, as noted above, 
and must contain the value 0. If the NAM block is extended in the 
future, the first byte will contain an identifier and the second byte 
will contain the (new) block length. 
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6.5.1 DID Field in NAM Block 



USE 

INIT 

SIZE 

ACCESS 

INPUT 



OUTPUT 



Contains the directory identifier for the target file 
None 



3 words 



$FETCH dst,DID,reg 



CREATE 

ENTER 

ERASE 

OPEN 

REMOVE 

RENAME 

SEARCH 

CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Di rectory 
Di rectory 
Di rectory 
Di rectory 
Di rectory 
Di rectory 
Di rectory 

Di rectory 
Di rectory 
Directory 
Di rectory 
Di rectory 
Di rectory 
Di rectory 
Di rectory 



;DID field to 3-word dst 

identifier 
ident i f ier 
ident i f ier 
ident i f ier 
identifier 
ident i f ier 
identifier 

ident i f ier 
ident i f ier 
ident i f ier 
identifier 

identifier (cleared) 
identifier 
ident i f ier 
identifier 
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6.5.2 DVI Field in NAM Block 



USE 

INIT 

SIZE 

ACCESS 

INPUT 



OUTPUT 



Contains the device identifier for the target file 
None 



2 words 



$FETCH dst,DVI,reg 



;DVI field to 2-word dst 



CREATE 

ENTER 

ERASE 

OPEN 

REMOVE 

RENAME 

SEARCH 

CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Device identifier 
Device identifier 
Device identifier 
Device identifier 
Device identifier 
Device identifier 
Device identifier 



Device 
Device 
Device 
Device 
Device 
Device 
Device 



identi f ier 
ident i f ier 
identi f ier 
ident i f ier 
identifier 
identifier 
identifier 
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6.5.3 ESA Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the expanded string buffer 
N$ESA address 
1 word 



$FETCH dst,ESA,reg 
$STORE src,ESA,reg 
$COMPARE src,ESA,reg 



CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Expanded 
Expanded 
Expanded 
Expanded 
Expanded 
Expanded 
Expanded 
Expanded 



;ESA field to 1-word dst 
;l-word src to ESA field 
;l-word src with ESA field 



string 
string 
s tr i ng 
string 
string 
str i ng 
string 
string 



buffer 
buffer 
buffer 
buf f er 
buffer 
buffer 
buffer 
buffer 



address 
address 
address 
address 
add ress 
address 
address 
address 
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6.5.4 ESL Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the length of the expanded string. 
None 



1 byte 

$FETCH dst,ESL,reg 
$COMPARE src,ESL,reg 



;ESL field to 1-byte dst 
;l-byte src with ESL field 



SEARCH 

CREATE 

ENTER 

ERASE 

OPEN 

PARSE 

REMOVE 

RENAME 



Expanded string length (bytes) 



Expanded 
Expanded 
Expanded 
Expanded 
Expanded 
Expanded 
Expanded 



string 
str ing 
string 
str i ng 
string 
str ing 
string 



length 
length 
length 
length 
length 
length 
length 



(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
(bytes) 
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6.5.5 ESS Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the expanded string buffer. 
N$ESS number 



1 byte 

$FETCH dst,ESS,reg 
$STORE src,ESS,reg 
$COMPARE src,ESS,reg 



;ESS field to 1-byte dst 
;l-byte src to ESS field 
;l-byte src with ESS field 



CREATE Expanded string buffer size (bytes) 

ENTER Expanded string buffer size (bytes) 

ERASE Expanded string buffer size (bytes) 

OPEN Expanded string buffer size (bytes) 

PARSE Expanded string buffer size (bytes) 

REMOVE Expanded string buffer size (bytes) 

RENAME Expanded string buffer size (bytes) 
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6.5.6 FID Field in NAM Block 



USE 

INIT 

SIZE 

ACCESS 

INPUT 

OUTPUT 



Contains the file identifier for the target file. 
None 



3 words 



$FETCH dst,FID,reg 



;FID field to 3-word dst 



ENTER 
ERASE 
OPEN 
REMOVE 

CREATE 

ERASE 

OPEN 

REMOVE 

RENAME 

SEARCH 



File identifier 

File identifier 

File identifier 

File identifier 



File 
File 
File 
File 
File 
File 



ident i f ier 
ident i f ier 
ident i f ier 
ident i f ier 
identifier 
ident i f ier 



(only if FB$F ID mask is set) 
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6.5.7 FNB Field in NAM Block 



USE 

INIT 
SIZE 
ACCESS 

MASKS 



OUTPUT 



Indicates which parts of the merged string were taken from 

the file string or the default string. (The masks in this 

section do not include the NB$WCH mask, which has its own 
description in the next section.) 

None 

1 word 

$TESTBITS mask, FNB, reg ;Test mask bits in FNB field 
$FETCH dst,FNB,reg ; FNB field to 1-word dst 

$COMPARE src,FNB,reg ;l-word src with FNB field 



NB$DEV 
NB$DIR 
NB$NAM 
NB$NOD 
NB$QUO 
NB$TYP 
NB$VER 
NB$WDI 

NB$WNA 

NB$WTY 

NB$WVE 



Device in file string or default string 
Directory in file string or default string 
File name in file string or default string 
Node in file string or default string 
Quoted string in file string or default string 
File type in file string or default string 
File version in file string or default string 



Wi ldcard 
string 
Wi ldcard 
s tr ing 
Wi ldcard 
string 
Wi ldcard 
string 



directory in file string 



or 



default 



file 



name in file 



file type in file 



str ing 
string 



or default 



or default 



file version in file string or default 



CREATE 


File 


specification 


mask 


ENTER 


File 


spec ification 


mask 


ERASE 


File 


specification 


mask 


OPEN 


File 


specification 


mask 


PARSE 


File 


speci f ication 


mask 


REMOVE 


File 


specification 


mask 


RENAME 


File 


specification 


mask 
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6.5.8 FNB Field in NAM Block (NB$WCH Mask) 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Indicates that a valid wildcard context exists. 



(Masks 



for the FNB field other than the NB$WCH mask are described 
in the previous section.) 

None 

1 word 

$TESTBITS mask, FNB, reg ;Test mask bits in FNB field 

$FETCH dst,FNB,reg ;FNB field to 1-word dst 

$COMPARE src,FNB,reg ;l-word src with FNB field 



ERASE 

OPEN 

REMOVE 

RENAME 

SEARCH 



Wi ldcard 
Wi ldcard 
Wi ldcard 
Wi ldcard 
Wi ldcard 



context 
context 
context 
context 
context 



established 
established 
established 
established 
establ ished 



OUTPUT CREATE Wildcard context established 

ENTER Wildcard context established 

OPEN Wildcard context established 

PARSE Wildcard context established 

SEARCH Wildcard context established 
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6.5.9 RSA Field in NAM Block 

USE Contains the address of the resultant string buffer. 

INIT N$RSA address 

SIZE 1 word 

ACCESS $FETCH dst,RSA,reg ;RSA field to 1-word dst 

$STORE src,RSA,reg ;l-word src to RSA field 

$COMPARE src,RSA,reg ;l-word src with RSA field 

INPUT SEARCH Resultant string buffer address 
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6 ..5. 10 RSL Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the length of the resultant string. 

None 
1 byte 

$FETCH dst,RSL,reg ;RSL field to 1-byte dst 

$COMPARE src,RSL,reg ; 1-byte src with RSL field 

SEARCH Resultant string length (bytes) 

SEARCH Resultant string length (bytes) 
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6.5.11 RSS Field in NAM Block 

USE Contains the size of the resultant string buffer. 

INIT N$RSS number 

SIZE 1 byte 

ACCESS $FETCH dst,RSS,reg ;RSS field to 1-byte dst 

$STORE src,RSS,reg ;l-byte src to RSS field 

$COMPARE src,RSS,reg ;l-byte src with RSS field 

INPUT SEARCH Resultant string buffer size (bytes) 
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6.5.12 WCC Field in NAM Block 



USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains wildcard context information. 

None 

1 word 

$FETCH dst,WCC,reg ;WCC field to 1-word dst 

$COMPARE src,WCC,reg ;l-word src with WCC field 

SEARCH Wildcard context 

PARSE Wildcard context 

SEARCH Wildcard context 
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6.5.13 

USE 
INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



WDI Field in NAM Block 



Contains wildcard directory context information. 
None 



1 word 



$FETCH dst,WDI,reg ;WDI field to 1-word dst 

$COMPARE src,WDI,reg ; 1-word src with WDI field 

SEARCH Wildcard directory context 

PARSE Wildcard directory context 

SEARCH Wildcard directory context 
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6.6 PRO BLOCK SUMMARY 

This section summarizes the PRO block and its fields. Table 6-6 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-6: PRO Block Summary 





Offset 


Field 




Offset 


Symbol 


Size 


Description 


000 


0$COD 


1 


byte 


PRO block identifier 










000003 XB$PRO PRO block identifier code 


001 


0$BLN 


1 


byte 


PRO block length (bytes) 










000012 XB$PRL PRO block length (bytes) 


002 


0$NXT 


1 


word 


Next XAB address 


004 


0$PRG 


1 


word 


Programmer or member portion of file 










owner code 


006 


0$PRJ 


1 


word 


Project or group portion of file owner 










code 


010 


0$PRO 


1 


word 


File protection code 
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6.6.1 BLN Field in PRO Block (XB$PRL Code) 

USE Contains the length of the PRO block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 
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6.6.2 COD Field in PRO Block (XB$PRO Code) 

USE Contains the identifier for the PRO block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ;l-byte src with COD field 
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6.6.3 NXT Field in PRO Block 



OSE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the next XAB (ALL, DAT, KEY, 
or SUM block) in a chain of XABs . 

X$NXT address 

1 word 



PRO, 



$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



CLOSE 

CREATE 

DISPLAY 

ENTER 

ERASE 

EXTEND 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 



XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 



;NXT field to 1-word dst 
;l-word src to NXT field 
;l-word src with NXT field 

address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
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6.6.4 PRG Field in PRO Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the member or programmer portion of the file 
owner code. 

X$PRG number 

1 word 



$FETCH dst,PRG,reg 
$STORE src,PRG,reg 
$COMPARE src,PRG,reg 



PRG field to 1-word dst 
1-word src to PRG field 
1-word src with PRG field 



CLOSE Programmer or member portion of file owner 

code 

DISPLAY Programmer or member portion of file owner 

code 

OPEN Programmer or member portion of file owner 

code 
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6.6.5 PRJ Field in PRO Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 
OUTPUT 



Contains the group or project portion of the file owner 
code . 

X$PRJ number 
1 word 



$FETCH dst,PRJ,reg 
$STORE src,PRJ,reg 
$COMPARE src,PRJ,reg 



;PRJ field to 1-word dst 
;l-word src to PRJ field 
;l-word src with PRJ field 



CLOSE Project or group portion of file owner code 

DISPLAY Project or group portion of file owner code 

OPEN Project or group portion of file owner code 
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6.6.6 PRO Field in PRO Block 



USE 
INIT 
SIZE 
ACCESS 

INPOT 
OUTPUT 



Contains the protection code for the file. 
X$PRO number 
1 word 



$FETCH dst,PRO,reg 
$STORE src,PRO,reg 
$COMPARE src,PRO,reg 



;PRO field to 1-word dst 
;l-word src to PRO field 
; 1-word src with PRO field 



CLOSE File protection code 

CREATE File protection code 

DISPLAY File protection code 

OPEN File protection code 
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6.7 RAB SUMMARY 

This section summarizes the RAB and its fields. Table 6-7 summarizes 
the entire block, giving the offset, offset symbol, size, and a brief 
description for each field; for a field that has mask or code 
symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 

Table 6-7: RAB Summary 



Offset Field 
Offset Symbol Size Description 



000 0$BID 1 byte 



001 0$BLN 1 byte 



002 


0$CTX 


1 


word 


004 


0$ISI 


1 


word 


006 


0$STS 


1 


word 


010 


0$STV 


1 


word 


012 


0$RFA 


3 


words 


020 


0$RAC 


1 


byte 



021 
022 



0$KSZ 
0$ROP 



1 byte 
1 word 



RAB identifier code 

000001 RB$BID RAB identifier 

RAB length (bytes) 

000120 RB$BLN Synchronous RAB length 
(bytes) 

000240 RB$BLL Asynchronous RAB length 
(bytes) 

User context 

Internal stream identifier 
Completion status code 
Completion status value 
Record file address 
Record access code 

000000 RB$SEQ Sequential access 

000001 RB$KEY Key access 

000002 RB$RFA RFA access 

Key size (bytes) 

Record processing option mask 



000001 


RB$EOF 


000002 


RB$MAS 


000020 


RB$LOA 


000100 


RB$LOC 


000200 


RB$ASY 


002000 


RB$KGE 


004000 


RB$KGT 


010000 


RB$FDL 


020000 


RB$UIF 



Position to end-of-file 
Mass insert 

Honor bucket fill numbers 
Locate mode 

Asynchronous operation 

Greater-than-or-equal key 

criterion 

Greater-than key 

criterion 

Fast deletion 

Update if record exists 



024 


0$USZ 


1 


word 


User buffer size (bytes) 


026 


0$UBF 


1 


word 


User buffer address 


030 


0$RSZ 


1 


word 


Record size (bytes) 


032 


0$RBF 


1 


word 


Record buffer address 


034 


0$KBF 


1 


word 


Key buffer address 


036 


0$KRF 


1 


byte 


Key of reference 


037 


0$MBF 


1 


byte 


Multibuffer count 


040 


0$MBC 


1 


byte 


Multiblock count 


041 


0$RT1A 


1 


byte 


Reserved 


042 


0$RHB 


1 


word 


VFC control buffer address 


044 


0$FAB 


1 


word 


FAB address 


046 


0$BKT 


2 


words 


Virtual block number (VBN) or relative 










record number (RRN) 
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6.7.1 BID Field in RAB (RB$BID Code) 

USE Contains the identifier for the RAB. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BID,reg ;BID field to 1-byte dst 

$COMPARE src,BID,reg ;l-byte src with BID field 
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6.7.2 BKT Field in RAB 



USE 

INIT 
SIZE 
ACCESS 



INPUT 



OUTPUT 



Contains a virtual block number or relative record 
for a target record. 

R$BKT number 

2 words 



number 



$FETCH dst,BKT,reg 
$STORE src,BKT,reg 
$FETCH dst,BKTn,reg 
$STORE src,BKTn,reg 
$COMPARE src,BKTn,reg 



;BKT field to 2-word dst 
; 2-word src to BKT field 
;BKT word n to 1-word dst 
; 1-word src to BKT word n 
; 1-word src with BKT word n 



READ 

SPACE 

WRITE 

FIND 

GET 

PUT 



Virtual block number (VBN) 

Virtual block number (VBN) increment 

Virtual block number (VBN) 

Relative record number (RRN) 
Relative record number (RRN) 
Relative record number (RRN) 
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6.7.3 BLN Field in RAB 

USE Contains the length of the RAB. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ; 1-byte src with BLN field 

CODES RB$BLL Asynchronous RAB length (bytes) 

RB$BLN Synchronous RAB length (bytes) 
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6.7.4 CTX Field in RAB 



USE Contains any information you may want to associate with 

the stream at run time. 

INIT R$CTX number 

SIZE 1 word 

ACCESS $FETCH dst f CTX,reg ;CTX field to 1-word dst 

$STORE src,CTX,reg ;l-word src to CTX field 

* $COMPARE src,CTX,reg ; 1-word src with CTX field 
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6.7.5 FAB Field in RAB 



USE 
INIT 
SIZE 
ACCESS 



Contains the address of the FAB for the target file 
R$FAB address 
1 word 



$FETCH dst,FAB,reg 
$STORE src,FAB,reg 
$COMPARE src,FAB,reg 



; FAB field to 1-word dst 
;l-word src to FAB field 
;l-word src with FAB field 



INPUT 



CONNECT 



FAB address 
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6.7.6 ISI Field in RAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the internal stream 
file. 

None 

1 word 



identifier for the target 



OUTPUT 



$FETCH dst, 


ISI ,reg 


; ISI 


field to 1- 


$COMPARE src,ISI,reg 


; 1-word src with 


DELETE 


Internal 


stream 


identi f ier 


DISCONNECT 


Internal 


stream 


identifier 


FIND 


Internal 


stream 


identifier 


FLUSH 


Internal 


stream 


identifier 


FREE 


Internal 


stream 


identifier 


GET 


Internal 


stream 


identifier 


NXTVOL 


Internal 


stream 


ident i f ier 


PUT 


Internal 


stream 


identifier 


READ 


Internal 


stream 


identi f ier 


REWIND 


Internal 


stream 


identifier 


SPACE 


Internal 


stream 


ident i f ier 


TRUNCATE 


Internal 


stream 


identifier 


UPDATE 


Internal 


stream 


ident i f ier 


WAIT 


Internal 


stream 


identifier 


WRITE 


Internal 


stream 


identi f ier 


CONNECT 


Internal 


stream 


identifier 


DISCONNECT 


Internal 


stream 


ident i f ier 
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6.7.7 KBF Field in RAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the 
record . 

R$KBF address 

1 word 



key buffer for the target 



$FETCH dst,KBF,reg 
$STORE src,KBF,reg 
$COMPARE src,KBF,reg 



KBF field to 1-word dst 
1-word src to KBF field 
1-word src with KBF field 



FIND 

GET 

PUT 



Key buffer address 
Key buffer address 
Key buffer address 
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6.7.8 KRF Field in RAB 



USE Contains the index reference number of the index for the 

operation . 

INIT R$KRF number 

SIZE 1 byte 

ACCESS $FETCH dst,KRF,reg ; KRF field to 1-byte dst 

$STORE src,KRF,reg ;l-byte src to KRF field 

$COMPARE src,KRF,reg ;l-byte src with KRF field 

INPUT CONNECT Key of reference 

FIND Key of reference 

GET Key of reference 

REWIND Key of reference 
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6.7.9 KSZ Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the record key for the operation 
R$KSZ number 



1 byte 

$FETCH dst,KSZ,reg 
$STORE src,KSZ,reg 
$COMPARE src,KSZ,reg 



;KSZ field to 1-byte dst 
;l-byte src to KSZ field 
;l-byte src with KSZ field 



FIND 

GET 

PUT 



Key size (bytes) 
Key size (bytes) 
Key size (bytes) 
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6.7.10 MBC Field in RAB 

USE Contains the multiblock count for the stream. 

INIT R$MBC number 

SIZE 1 byte 

ACCESS $FETCH dst,MBC,reg ;MBC field to 1-byte dst 

$STORE src,MBC,reg ;l-byte src to MBC field 

$COMPARE src,MBC,reg ;l-byte src with MBC field 

INPUT CONNECT Multiblock count 
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6.7.11 MBF Field in RAB 

USE Contains the multibuffer count for the stream. 

INIT R$MBF number 

SIZE 1 byte 

ACCESS $FETCH dst,MBF,reg ;MBF field to 1-byte dst 

$STORE src,MBF,reg ;l-byte src to MBF field 

$COMPARE src,MBF,reg ;l-byte src with MBF field 

INPUT CONNECT Multibuffer count 
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6.7.12 RAC Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

CODES 

INPUT 



Contains the access mode code for the operation. 
R$RAC code 



1 byte 

$FETCH dst,RAC,reg 
$STORE src,RAC,reg 
$COMPARE src,RAC,reg 



;RAC field to 1-byte dst 
;l-byte src to RAC field 
; 1-byte src with RAC field 



RB$KEY Key access 
RB$RFA RFA access 
RB$SEQ Sequential access 



FIND 

GET 

PUT 



Record access code 
Record access code 
Record access code 
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6.7.13 RBF Field in RAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 

OUTPUT 



Contains the 
operation . 

R$RBF address 

1 word 



$FETCH dst,RBF,reg 
$STORE src,RBF,reg 
$COMPARE src,RBF,reg 



address of the record buffer for 



the 



RBF field to 1-word dst 
1-word src to RBF field 
1-word src with RBF field 



PUT Record buffer address 

UPDATE Record buffer address 

WRITE Record buffer address 

CONNECT Record buffer address 

GET Record buffer address 

PUT Record buffer address 

READ Record buffer address 
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6.7.14 

USE 

INIT 

SIZE 

ACCESS 

INPDT 

OUTPUT 



RFA Field in RAB 



Contains the record file address for the target record. 
None 



3 words 

$FETCH dst,RFA,reg ; RFA field to 3-word dst 



FIND Record file address 

GET Record file address 

CONNECT End-of-file address 

FIND Record file address 

GET Record file address 

PUT Record file address 

READ Virtual block number (2 words) 

WRITE Virtual block number (2 words) 
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6.7.15 RHB Field in RAB 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the VFC fixed control area buffer 
for the target record. 

R$RHB address 

1 word 



$FETCH dst,RHB,reg 
$STORE src,RHB,reg 
$COMPARE src,RHB,reg 



; RHB field to 1-word dst 
; 1-word src to RHB field 
;l-word src with RHB field 



GET VFC control buffer address 

PUT VFC control buffer address 

UPDATE VFC control buffer address 
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6.7.16 ROP Field in RAB (RB$ASY Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests asynchronous operation. 
R$ROP mask 
1 word 

$SET mask , ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTB ITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



CONNECT 

DELETE 

DISCONNECT 

FIND 

FLUSH 

FREE 

GET 

NXTVOL 

PUT 

READ 

REWIND 

SPACE 

TRUNCATE 

UPDATE 

WRITE 



Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 
Asynch 



ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 
ronous 



oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 
oper 



at ion 
at ion 
at ion 
at ion 
at ion 
ation 
at ion 
ation 
ation 
ation 
ation 
ation 
at ion 
ation 
ation 
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6.7.17 ROP Field in RAB (RB$EOF Mask) 



OSE Requests initial stream context at end-of-f i le . 

INIT R$ROP mask 

SIZE 1 word 

ACCESS $SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ; 1-word src with ROP field 

IN POT CONNECT Position to end-of-file 
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6.7.18 ROP Field in RAB (RB$FDL Mask) 



USE Requests fast deletion. 

INIT R$ROP mask 

SIZE 1 word 

ACCESS $SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



INPUT 



DELETE 



Fast deletion 
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6.7.19 ROP Field in RAB (RB$KGE Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests greater-than-or-equal key match criterion 
R$ROP mask 
1 word 



$SET mask, ROP, reg 
$OFF mask, ROP, reg 
$TESTB ITS mask, ROP, reg 
$FETCH dst,ROP,reg 
$STORE src,RQP,reg 
$COMPARE src,ROP,reg 



Mask bits on in ROP field 
Mask bits off in ROP field 
Test mask bits in ROP field 
ROP field to 1-word dst 
1-word src to ROP field 
1-word src with ROP field 



FIND 
GET 



Greater-than-or-equal key criterion 
Greater-than-or-equal key criterion 
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6.7.20 

USE 
INIT 
SIZE 
ACCESS 



INPUT 



ROP Field in RAB (RB$KGT Mask) 



Requests greater-then key match criterion. 
R$ROP mask 
1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTB ITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src, ROP, reg ;l-word src to ROP field 

$COMPARE src,ROP,reg ;l-word src with ROP field 

FIND Greater-than key criterion 

GET Greater-than key criterion 
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6.7.21 ROP Field in RAB (RB$LOA Mask) 



USE 
INIT 
SIZE 
ACCESS 



INPUT 



Requests bucket fill number honoring. 
R$ROP mask 
1 word 



$SET mask, ROP, reg 
$OFF mask, ROP, reg 
$TESTBITS mask, ROP, reg 
$FETCH dst,ROP,reg 
$STORE src,ROP,reg 
$COMPARE src, ROP, reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
;Test mask bits in ROP field 
;ROP field to 1-word dst 
;l-word src to ROP field 
;l-word src with ROP field 



PUT 

UPDATE 



Honor 
Honor 



bucket 
bucket 



fill 
fill 



numbers 
numbers 
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6.7.22 ROP Field in RAB (RB$LOC Mask) 



USE Requests locate mode operation. 
INIT R$ROP mask 
SIZE 1 word 

ACCESS $SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 
$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 



INPUT 



CONNECT 

GET 

PUT 



Locate mode 
Locate mode 
Locate mode 
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6.7.23 ROP Field in RAB (RB$MAS Mask) 



USE 
INIT 
SIZE 
ACCESS 



Requests mass insertion. 
R$ROP mask 
1 word 



$SET mask, ROP, reg 
$OFF mask, ROP, reg 
$TESTB ITS mask, ROP, reg 
$FETCH dst,ROP,reg 
$STORE src, ROP, reg 
$COMPARE src, ROP, reg 



;Mask bits on in ROP field 
;Mask bits off in ROP field 
;Test mask bits in ROP field 
;ROP field to 1-word dst 
;l-word src to ROP field 
;l-word src with ROP field 



INPUT 



PUT 



Mass insert 



6-138 



CONTROL BLOCK FIELDS 
RAB SUMMARY 



6.7.24 

USE 
INIT 
SIZE 
ACCESS 



INPUT 



ROP Field in RAB (RB$UIF Mask) 



Requests update if target record already exists. 
R$ROP mask 
1 word 

$SET mask, ROP, reg ;Mask bits on in ROP field 

$OFF mask, ROP, reg ;Mask bits off in ROP field 

$TESTBITS mask, ROP, reg ;Test mask bits in ROP field 

$FETCH dst,ROP,reg ;ROP field to 1-word dst 

$STORE src,ROP,reg ;l-word src to ROP field 

$COMPARE src, ROP, reg ;l-word src with ROP field 

PUT Update if record exists 
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6.7.25 RSZ Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

INPUT 

OUTPUT 



Contains the size of the target record. 
R$RSZ number 
1 word 



$FETCH dst,RSZ,reg 
$STORE src,RSZ,reg 
$COMPARE src,RSZ,reg 



;RSZ field to 1-word dst 
; 1-word src to RSZ field 
;l-word src with RSZ field 



PUT Record size (bytes) 

UPDATE Record size (bytes) 

WRITE Record size (bytes) 

GET Record size (bytes) 

READ Record size (bytes) 
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6.7.26 STS Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the completion status code for the operation 

None 

1 word 



$FETCH dst, 


STS,reg 


;STS field to 1-word 


dst 


$COMPARE src,STS,reg 


; 1-word 


src with STS 


field 


CONNECT 


Completion 


status 


code 




DELETE 


Completion 


status 


code 




DISCONNECT 


Completion 


status 


code 




FIND 


Completion 


status 


code 




FLUSH 


Completion 


status 


code 




FREE 


Completion 


status 


code 




GET 


Complet i on 


status 


code 




NXTVOL 


Completion 


status 


code 




PUT 


Completion 


status 


code 




READ 


Completion 


status 


code 




REWIND 


Completion 


status 


code 




SPACE 


Completion 


status 


code 




TRUNCATE 


Completion 


status 


code 




UPDATE 


Completion 


status 


code 




WRITE 


Completion 


status 


code 
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6.7.27 STV Field in RAB 



USE 
INIT 
SIZE 
ACCESS 

OUTPUT 



Contains the completion status value for the operation 
None 



1 word 

$FETCH dst,STV,reg 
$COMPARE src,STV,reg 



;STV field to 1-word dst 
;l-word src with STV field 



CONNECT 

DELETE 

DISCONNECT 

FIND 

FLUSH 

FREE 

GET 

NXTVOL 

PUT 

READ 

REWIND 

SPACE 

TRUNCATE 

UPDATE 

WRITE 



Completion 
Completion 
Complet ion 
Completion 
Completion 
Completion 
Completion 
Completion 
Complet ion 
Completion 
Completion 
Completion 
Completion 
Completion 
Completion 



status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 
status 



value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
value 
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6.7.28 

USE 
INIT 
SIZE 
ACCESS 

INPUT 



UBF Field in RAB 



Contains the address of the user buffer for the operation. 
R$UBF address 
1 word 

$FETCH dst,UBF,reg ;UBF field to 1-word dst 

$STORE src,UBF,reg ;l-word src to UBF field 

$COMPARE src,UBF,reg ;l-word src with UBF field 

CONNECT User buffer address 

GET User buffer address 

PUT User buffer address 

READ User buffer address 
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6.7.29 USZ Field in RAB 



DSE 
INIT 
SIZE 
ACCESS 

INPUT 



Contains the size of the user buffer for the operation 
R$USZ number 
1 word 



$FETCH dst,USZ,reg 
$STORE src,USZ,reg 
$COMPARE src,USZ,reg 



USZ field to 1-word dst 
1-word src to USZ field 
1-word src with USZ field 



CONNECT User buffer size (bytes) 

GET User buffer size (bytes) 

PUT User buffer size (bytes) 

READ User buffer size (bytes) 
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6.8 SUM BLOCK SUMMARY 

This section summarizes the SUM block and its fields. Table 6-8 
summarizes the entire block, giving the offset, offset symbol, size, 
and a brief description for each field; for a field that has mask or 
code symbols, the table also gives the value, symbol, and a brief 
description for each mask or code. 



Table 6-8: SUM Block Summary 



Offset Field 
Offset Symbol Size Description 



000 


0$COD 


1 


byte 


SUM block identifier 










000005 XB$SUM SUM block 


001 


0$BLN 


1 


byte 


SUM block length (bytes) 










000012 XB$SML SUM block 


002 


0$NXT 


1 


word 


Next XAB address 


004 


0$NOK 


1 


byte 


Number of indexes 


005 


0$NOA 


1 


byte 


Number of areas 


006 


0$NOR 


1 


byte 


Reserved 


007 




1 


byte 


Reserved 


010 


0$PVN 


1 


word 


Prologue version number 
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6.8.1 BLN Field in SUM Block (XB$SML Code) 

USE Contains the length of the SUM block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,BLN,reg ;BLN field to 1-byte dst 

$COMPARE src,BLN,reg ;l-byte src with BLN field 
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6.8.2 COD Field in SUM Block (XB$SUM Code) 

USE Contains the identifier for the SUM block. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,COD,reg ;COD field to 1-byte dst 

$COMPARE src,COD,reg ;l-byte src with COD field 
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6.8.3 NOA Field in SUM Block 

USE Contains the number of areas in the file. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,NOA,reg ;NOA field to 1-byte dst 

$COMPARE src,NOA,reg ;l-byte src with NOA field 

OUTPUT DISPLAY Number of areas 

OPEN Number of areas 
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6.8.4 NOK Field in SUM Block 

USE Contains the number of indexes in the file. 

INIT None 
SIZE 1 byte 

ACCESS $FETCH dst,NOK,reg ;NOK field to 1-byte dst 

$COMPARE src,NOK,reg ; 1-byte src with NOK field 

OUTPUT DISPLAY Number of indexes 

OPEN Number of indexes 
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6.8.5 NXT Field in SUM Block 



USE 

INIT 
SIZE 
ACCESS 

INPUT 



Contains the address of the next XAB (ALL , DAT, KE 
or SUM block) in a chain of XABs . 

X$NXT address 

1 word 



$FETCH dst,NXT,reg 
$STORE src,NXT,reg 
$COMPARE src,NXT,reg 



CLOSE 

CREATE 

DISPLAY 

ENTER 

ERASE 

EXTEND 

OPEN 

PARSE 

REMOVE 

RENAME 

SEARCH 



Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 
Next 



XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 
XAB 



;NXT field to 1-word dst 
;l-word src to NXT field 
;l-word src with NXT field 

address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
address 
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6.8.6 PVN Field in SUM Block 



USE Contains the prologue version number for the file. 

INIT None 
SIZE 1 word 

ACCESS $FETCH dst,PVN,reg ;PVN field to 1-word dst 

$COMPARE src,PVN,reg ; 1-word src with PVN field 

OUTPUT DISPLAY Prologue version number 

OPEN Prologue version number 
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This chapter contains example programs; the titles of the programs 
are : 

• PARSE - $PARSE TEST 

• SEARCH - $SEARCH TEST 

• ERASE - $ERASE TEST 

• RENAME - $RENAME TEST 

• GSA - CORE SPACE ALLOCATOR 

Sections 7.1 through 7.4 contain these programs and give instructions 
for building and running them. 

NOTE 

References to [uic] in the command lines 
in the following sections indicate that 
you should include your default UIC. 

Each program requires the GSA routine (Section 7.5) for allocating 
dynamic memory: 

MAC SY:GSA = LB: [1,1] RMS MAC /ML , SY : [uicjGSA 
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7.1 PARSE - $PARSE TEST 

The following shows how to build the PARSE program (Example 7-1) and 
shows a brief sample run of the program. 

MAC S Y : PARSE=LB : [1,1] RMSMAC/ML , S Y : [uic] PARSE 
T KB 

TKB>SY: PARS E/CP=SY: PARSE, SY:GSA 
TKB > LB : [1,1] VML IB/LB: INIDM : EXTSK 
TKB> LB : [1,1] RMS L IB/ LB 
TKB> / / 

RUN DB1 : [ 200 , 1] PARSE 
Enter the default name string: DBO : 
Enter the primary name string: .LOG 
$PARSE expanded string is DBO : [ 70 , 5 ] . LOG 

File name bits (FNB) are 004202 

(DEV, TYP) 
Enter the default name string: ~Z 
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Example 7-1: PARSE - $PARSE Test 



.TITLE PARSE - $PARSE TEST 

. IDENT /X01.00/ 

. ENABL LC 

.MCALL FAB$B , NAM$B , GSA$ 

. MCALL $PARSE , $STORE , $FETCH , $COMPARE 

.MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS- 11 $PARSE function. 



RMS-11 Data Structures 



GSA$ 



GSA 



FAB 



FAB$B 
F$NAM 
F$LCH 

FAB$E 



NAM 
2. 



Argument FAB 
Link to NAM 
Channel #2 



NAM 



NAM$B 
N$ESA 
N$ESS 

NAM$E 



EXPSTR 
128. 



NAM definition 
EXP STR address 
EXP STR length 



PARSE: : 



. PSECT 


$CODE$, RO, I 




ALUN$S 


#1,#"TI,#0 


Assign the terminal 


MOV 


#FAB,R0 


Map the target FAB 


MOV 


#EDBLK , R2 


; Map the exit block 


MOV 


#NAM , R3 , 


Map the target NAM 


MOV 


#READ , R4 


Map the input DPB 


MOV 


#WRITE,R5 , 


Map the output DPB 


CLR 


Q. IOPL+4 (R5) 


Turn off carriage ctl 


MOV 


#QUES1,Q. IOPL (R5! 




MOV 


#QUES1L,Q. IOPL+2 (R5) 


DIR$ 


R5 


Prompt for the DNA 


TSTB 


IOSTAT 


• Check the IOSB 


BMI 


EXIT 


Exit if error 


MOV 


#BUFF1,Q. IOPL (R4) 




MOV 


#64. ,Q. IOPL+2 (R4) 


DIR$ 


R4 


• Get the response 


TSTB 


IOSTAT , 


Check the IOSB 


BMI 


EXIT 


; Exit if error 


$STORE 


IOLEN,DNS,R0 


Set the default length 


$STORE 


#BUFF1 , DNA , RO 


; Set the default address 


MOV 


#QUES2,Q. IOPL (R5) 


MOV 


#QUES2L,Q. IOPL+2 (R5) 


DIR$ 


R5 


Prompt for the DNA 


TSTB 


IOSTAT 


; Check the IOSB 


BMI 


EXIT , 


Exit if error 


MOV 


#BUFF2,Q. IOPL (R4) 


MOV 


#64. ,0. IOPL+2 (R4) 


DIR$ 


R4 


; Get the response 


TSTB 


IOSTAT , 


Check the IOSB 


BMI 


EXIT 


; Exit if error 
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EXIT 



ERROR: 



BITS: 



2$: 

4$: 

6$: 

8$: 

10$: 

12$: 

14$: 

16$: 

18$: 

20$: 

PRINT 



$STORE IOLEN , FNS , R0 

$STORE #BUFF2, FNA, RO 

MOV #40,Q. IOPL+4 (R5) 

$PARSE RO 

$COMPARE #0,STS,R0 

BLT ERROR 

CLR (R2) 

$FETCH (R2),ESL,R3 

TST (R2)+ 

$FETCH (R2)+,ESA,R3 

$FETCH (R2) , FNB , R3 

MOV #ESSSTR,R1 

CALL PRINT 

CALL BITS 

BR PARSE 



EXIT$S 



$FETCH 

$FETCH 

MOV 

CALL 

BR 



MOV 

$FETCH 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

BIT 

BEQ 

MOV 

MOV 

MOV 

CALL 

RETURN 



MOV 



(R2) +, STS,R0 
(R2) ,ST.V,R0 
#ERRSTR,R1 
PRINT 
PARSE 



#EDBLK / R2 
R0,FNB,R3 
#2000, RO 
2$ 

#QUO, (R2)+ 
#1000, RO 
4$ 

#WDI , (R2) + 
#400, RO 

6$ 

#NOD, (R2) + 
#100, RO 
8$ 

#DIR, (R2) + 
#40, RO 
10$ 

#WNA, (R2) + 
#20, RO 
12$ 

#WTY, (R2) + 
#10, RO 
14$ 

#WVE, (R2) + 
#4,R0 

16$ 

#NME, (R2) + 
#2,R0 

18$ 

#TYP, (R2) + 

#1,R0 

20$ 

#VER, (R2) + 
#END, (R2) 
#DEV,R1 
PRINT 



#EDBLK,R2 



Set the default length 
Set the default address 
Restore carriage control 
Parse the strings 
An error? 

Yes if MI; display it 

Init the length 

Get the string length 

Advance 

Get the string address 
Get the file name bits 
Select the format string 
Display the file 
Do the FNB bit disply 
And let's try another 



; Task exit 



Set the STS returned 
And the STV 

Set the error format string 
Go edit and print the message 
Let's try this again 



Init EDBLK address 
Get the FNB bits 
Quoted string? 
No if EQ 

Set Quoted string 
Wild directory? 
No if EQ 

Set wild directory 

Node spec? 

No if EQ 

Set nodespec 

Directory spec? 

No if EQ 

Set directory 

Wild name? 

No if eq 

Set wild name 

Wild type? 

No if EQ 

Set wild type 

Wild version? 

No if EQ 

Set wild version 

Name? 

No if EQ 

Set name 

Type? 

No if EQ 

Set type 

Version? 

No if EQ 

Set version 

End with a null . . . 

Set the default (dev) 

Edit and print 

And exit 



Setup edit 
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MOV 


#BUFFER, RO ; Output buffer 




CALL 


$EDMSG ; Exit the string 




MOV 


#BUFFER,Q. IOPL (R5) 




MOV 


R1,Q. IOPL+2 (R5) 




DIR$ 


R5 ; Send to the terminal 




RETURN 


; Return to caller 




. PSECT 


$DATA$ r RW , D 


QUES1: 


. Asci i 


<15><12>"Enter the default name string: 




QUES1L 


= . - QUES1 


QUES2: 


.Asci i 


<15><12>"Enter the primary name string: 




QUES2L 


= . - QUES2 


ERRSTR: 


. Asci z 


"$PARSE error — STS=%P, STV=%P" 


ESSSTR: 


.Asci i 


"$PARSE expanded string is %VA%N" 




. Asci z 


11 File name bits (FNB) are %P" 


DEV: 


. Asci z 


" (DEV%I" 


NOD : 


.Asci z 


", NOD%I" 


DIR: 


. Asci z 


DIR%I" 


NME: 


.Asci z 


", NAM% 1 11 


QUO: 


. Asci z 


QUO%I" 


TYP : 


.Asci z 


" , TYP%I" 


VER: 


. Asci z 


", VER%I" 


WDI : 


. Asc i z 


" , WDI%I" 


WNA; 


. Asci z 


" , WNA%I" 


WTY: 


. Asci z 


", WTY%I" 


WVE : 


. Asci z 


" , WVE%I" 


END: 


. Asci z 


") " 




. EVEN 




EDBLK: 


.BLKW 


16 . 


BUFFER: 






BUFFI: 


.Blkb 


64 . 


BUFF2 : 


• Blkb 


64 


EXPSTR: 


.BLKB 


128 . 


IOSTAT: 


.WORD 





IOLEN : 


.WORD 





READ : 


QIOW$ 


IO.RLB, 1, 1, , IOSTAT 


WRITE: 


QIOW$ 


IO.WLB, 1, 1, , IOSTAT, ,< , ,40> 




.END 


PARSE 
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7.2 SEARCH - $SEARCH TEST 



The following shows how to build the SEARCH program (Example 7-2) and 
shows a brief sample run of the program. 

MAC S Y : SEARCH=LB : [1,1] RMSMAC/ML , SY : [uic]SEARCH 
TKB 

TKB> S Y : SEARCH/CP=SY : SEARCH , S Y : GSA 
TKB > LB: [1,1] VML IB/LB: INIDM : EXTSK 
TKB> LB : [1,1] RMSL IB/LB 
T KB > // 

RUN DB1: [200 , 1] SEARCH 



Enter a wildcard filespec: VHC 1 



DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 
DBO 



70,5] VHC.SEQ;1 
70,5] VHC.INX;7 

70,5] VHCKR0.DES;3 
70,5] VHC.DES;2 
70,5] VHC.MST;1 
70,5] VHC.ERR;1 

70,5] VHC.KR0;1 
70,5] VHC.KR1;1 
70,5] VHCKR0. INX;3 



Total of 9 files matching DBO : [70 , 5 ] VHC* . * 

Enter a wildcard filespec: [70,*]CUST.* 

DBO: [70,10]CUST.FILE;1 
DBO: [70,10]CUST.SEQ;1 
DBO: [70,5]CUST.MST; 1 
DBO: [70,5]CUST.FIL;1 

Total of 4 files matching DBO : [ 70 , * ] CUST . * 
Enter a wildcard filespec: ~Z 
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Example 7-2: SEARCH - $SEARCH Test 



, TITLE SEARCH - $SEARCH TEST 

, IDENT /X01.00/ 

, ENABL LC 

, MCALL FAB$B,NAM$B,GSA$ 

, MCALL $ PARSE , $ SEARCH ,$ STORE , $ FETCH , $COMPARE 

.MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS-11 $SEARCH function. 



; RMS-11 Data Structures 
GSA$ GSA 



FAB 



NAM: 



FAB$B 
F$DNA 
F$DNS 
F$NAM 
F$LCH 

FAB$E 

NAM$B 
N$ESA 
N$ESS 
N$RSA 
N$RSS 

NAM$E 



SYDSKA 
SYDSKL 
NAM 
2. 



EXPSTR 
128. 
RESSTR 
128. 



Argument FAB 
If no device, SY 
should be used 
Link to NAM 
Channel #2 



NAM definition 
EXP STR address 
EXP STR length 
RES STR address 
RES STR length 



SEARCH:; : 



. PSECT 


$CODE$,RO, I 




ALUN$S 


#1,#"TI,#0 


Assign the terminal 


MOV 


#FAB,R0 , 


Map the target FAB 


MOV 


#EDBLK , R2 


Map the exit block 


MOV 


#NAM r R3 , 


Map the target NAM 


MOV 


#READ,R4 


Map the input DPB 


MOV 


#WRITE,R5 , 


Map the output DPB 


CLR 


Q. IOPL+4 (R5) 


Turn off carriage ctl 


MOV 


#QUES, Q. IOPL (R5) 




MOV 


#QUESL,Q. IOPL+2 (R5) 


DIR$ 


R5 


Prompt for the DNA 


TSTB 


IOSTAT 


Check the IOSB 


BMI 


EXIT , 


Exit if error 


MOV 


#BUFF,Q. IOPL (R4) 




MOV 


#64. ,Q. IOPL+2 (R4) 


DIR$ 


R4 


; Get the response 


TSTB 


IOSTAT , 


Check the IOSB 


BMI 


EXIT 


• Exit if error 


$STORE 


IOLEN , FNS , RO 


Set the string length 


$STORE 


#BUFF , FNA , RO 


Set the string address 


MOV 


#40, Q. IOPL+4 (R5) , 


Restore carriage control 


CLR 


FILCNT 


; Init count of matches 


$PARSE 


RO 


Parse the strings 


$COMPARE #0,STS,R0 


; An error? 


BLT 


ERROR 


Yes if MI; display it 



GETFIL: 
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NOTFST 



EXIT: 



ERROR: 



ERROR2 



ERRORO 



ERROR1 



PRINT 



MOV 


#EDBLK,R2 


; 


Reset the edit block addr 


$SEARCH 


RO 


; 


Get a matching file 


$COMPARE 


#0,STS,R0 


; 


Error? 


BLT 


ERROR 


; 


Yes if LT 


CLR 


(R2) 


; 


Init the length 


$FETCH 


(R2) , RSL , R3 


; 


Get the string length 


TST 


(R2) + 


\ 


Advance 


$FETCH 


( R2 ) + RS A R 3 




f^<^t" t"hfi Y f i nn 3 rl rl T" «; 


MOV 


#RSSSTR,R1 


; 


Select the format string 


TST 


FILCNT 


; 


First file needs a blank 


BNE 


NOTFST 


; 


line before it 


MOV 


#RSSST1,R1 


; 


Insert CR/LF first 


CALL 


PRINT 




Display the file 


MOV 


#FAB , RO 


[ 


Rest the FAB address 


INC 


FILCNT 




Count this file 


BR 


GETFIL 




And let's try another 


EXIT$S 






Task exit 


$COMPARE 


#ER$NMF,STS, RO 


; 


No more matches? 


BNE 


ERRORO 


; 


No - some other error 


MOV 


FILCNT, (R2) + 


; 


Set the cound of matches 


BEQ 


ERROR2 


; 


No files... 


CLR 


(R2) 




Give the ESA 


yC L 1 \ n 




; 


Ofc: L. LIlc icily UI1 


TST 


(R2) + 


; 


Advance word 


$FETCH 


(R2) , ESA , R3 


; 


Set the address 


MOV 


#TTLSTR, Rl 


; 


Set the format string 


BR 


ERROR1 


; 


Go show it and exit 


CLR 


-(R2) 




Setup for string length 


$FETCH 


( R 9 \ F^T R ^ 


: 




TST 


(R2) + 


; 


Advance to next word 


$FETCH 


(R2) , ESA, R3 


; 


Set the address 


MOV 


# NOF I LE , Rl 


I 


Set the format string 


BR 


i_j r\ r\ \j r\ j_ 


' 


fl 1 111 LlIC C I. I UL 


$FETCH 


(R2) +,STS,R0 




Set the STS returned 


$FETCH 


(R2) ,STV,R0 




And the STV 


MOV 


#ERRSTR ,R1 




Set the error format string 


CALL 


PRINT 


; 


Go edit and print the message 


JMP 


SEARCH 


; 


Let's try this again 


MOV 


#EDBLK, R2 


> 


Setup edit 


MOV 


#BUFFER, RO 




Output buffer 


CALL 


$EDMSG 


r 


Exit the string 


MOV 


#BUFFER,Q. IOPL (R5) 




MOV 


R1,Q. IOPL+2 (R5) 






DIR$ 


R5 


i 


Send to the terminal 


RETURN 




t 


Return to caller 





. PSECT 


$DATA$,RW f D 




SYDSKA: 


. Asc i i 


"SY:" 






SYDSKL 


= . - SYDSKA 




QUES: 


. Asci i 


<15><12>"Enter 


a wildcard filespec 




QUESL = 


. - QUES 




ERRSTR: 


.Asci z 


"$SEARCH error 


— STS=%P, STV=%P" 


RSSST1: 


. Asci i 


"%N" 




RSSSTR: 


.Asci z 


" %VA" 
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NOFILE: 


. Asci z 


"%NNo files 


matching %VA%N" 


TTLSTR: 


. Asci z 


"%NTotal of 


%D files matching 




.EVEN 






FILCNT: 


.WORD 







EDBLK : 


.BLKW 


6 




BUFFER: 








BUFF : 


.Blkb 


128 . 




EXPSTR: 


. BLKB 


128. 




RESSTR: 


.BLKB 


128. 




IOSTAT: 


.WORD 







IOLEN: 


.WORD 







READ: 


QIOW$ 


IO.RLB, 1, 1, 


, IOSTAT 


WRITE: 


QIOW$ 


IO.WLB, 1, 1, 


, IOSTAT, ,< , , 40> 




.END 


SEARCH 
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7.3 ERASE - $ERASE TEST 

The following shows how to build the ERASE program (Example 7-3) and 
shows a brief sample run of the program. 

MAC SY:ERASE=LB: [1, 1 ] RMSM AC/ML , S Y : [uic] ERASE 

TKB 

TKB>SY: ERASE/CP=SY: ERASE ,SY: GSA 
TKB>LB: [1,1] VMLIB/LB: INIDM : EXTSK 
TKB>LB: [1,1] RMS L IB/LB 
TKB> // 

RUN DB1 : [200,1] ERASE 
File(s) to erase: DES.XXX 

File DBO : [70 , 5] DES .XXX; 3 deleted 

Total of 1 files matching DBO : [ 70 , 5 ] DES . XXX deleted 

File(s) to erase: ~z 
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Example 7-3: ERASE - $ERASE Test 



, TITLE ERASE - $ERASE TEST 

IDENT /X01.00/ 

, ENABL LC 

, MCALL FAB$B , NAM$B , GSA$ 

i MCALL $PARSE , $ ERASE , $ STORE , $ FETCH , $COMPARE 

.MCALL ALUN$S,QIOW$,DIR$, EXIT$S 



This program tests/demonstrates the use of 

the RMS-11 $ERASE function, with implicit $SEARCH 



; RMS-11 Data Structures 
t 

GSA$ GSA 



FAB 



NAM: 



FAB$B 
F$DNA 
F$DNS 
F$NAM 
F$LCH 

FAB$E 

NAM$B 
N$ESA 
N$ESS 
N$RSA 
N$RSS 

NAM$E 



SYDSKA 
SYDSKL 
NAM 
2. 



EXPSTR 
128. 
RESSTR 
128. 



Argument FAB 
If no device, SY 
should be used 
Link to NAM 
Channel #2 



NAM definition 
EXP STR address 
EXP STR length 
RES STR address 
RES STR length 



ERASE: : 



. PSECT 


$CODE$,RO, I 






ALUN$S 


#1,#"TI,#0 




; Assign the terminal 


MOV 


#FAB,R0 




Map the target FAB 


MOV 


#EDBLK,R2 




; Map the exit block 


MOV 


#NAM , R3 




• Map the target NAM 


MOV 


#READ,R4 




; Map the input DPB 


MOV 


#WRITE, R5 




Map the output DPB 


CLR 


Q. IOPL+4 (R5) 




• Turn off carriage ctl 


MOV 


#QUES,Q. IOPL (R5) 




MOV 


#QUESL,Q. IOPL+2 (R5) 


DIR$ 


R5 




Prompt for the DNA 


TSTB 


IOSTAT 




; Check the IOSB 


BMI 


EXIT 




Exit if error 


MOV 


#BUFF,Q. IOPL 


(R4) 




MOV 


#64. ,Q. IOPL+2 (R4) 


DIR$ 


R4 




• r Get the response 


TSTB 


IOSTAT 




• Check the IOSB 


BMI 


EXIT 




; Exit if error 


$STORE 


IOLEN, FNS,R0 




• Set the string length 


$STORE 


#BUFF , FNA , RO 




; Set the string address 


MOV 


#40, Q. IOPL+4 


(R5) 


• Restore carriage control 


CLR 


FILCNT 




; Init count of matches 


$PARSE 


RO 




• Parse the strings 


$COMPARE #0,STS,R0 




; An error? 


BLT 


ERROR 




• Yes if MI; display it 



GETFIL: 
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NOTFST 



EXIT 



ERROR: 



ERROR2 



ERRORO 



ERROR1 



PRINT: 



MOV 


#EDBLK,R2 


Reset the edit block addr 


$ERASE 


RO ; 


Issue implicit $ERASE 


$COMPARE 


#0,STS,R0 


Error? 


BLT 


ERROR ; 


Yes if LT 


CLR 


(R2) ; 


Init the length 


$FETCH 


(R2) ,RSL,R3 ; 


Get the string length 


TST 


(R2)+ ; 


Advance 


$FETCH 


(R2) +, RSA, R3 ; 


Get the string address 


MOV 


#RSSSTR,R1 ; 


Select the format string 


TST 


FILCNT 


First file needs a blank 


BNE 


NOTFST ; 


line before it 


MOV 


#RSSST1,R1 


Insert CR/LF first 


CALL 


PRINT ; 


Display the file 


MOV 


#FAB , RO 


Rest the FAB address 


INC 


FILCNT ; 


Count this file 


BR 


GETFIL 


And let's try another 


EXIT$S 




Task exit 


$COMPARE 


#ER$NMF , STS , RO ; 


No more matches? 


BNE 


ERRORO ; 


No - some other error 


MOV 


FILCNT, (R2) + ; 


Set the cound of matches 


BEQ 


ERROR 2 ; 


No f i les . . . 


CLR 


(R2) ; 


Give the ESA 


$FETCH 


(R2) ,ESL,R3 ; 


Set the length 


TST 


(R2)+ ; 


Advance word 


$FETCH 


(R2) ,ESA,R3 


Set the address 


MOV 


#TTLSTR, Rl ; 


Set the format string 


BR 


ERROR1 


Go show it and exit 


CLR 


-(R2) ; 


Setup for string length 


$FETCH 


(R2) , ESL,R3 ; 


Set the length 


TST 


(R2)+ ; 


Advance to next word 


$FETCH 


(R2) ,ESA,R3 ; 


Set the address 


MOV 


#NOFILE , Rl ; 


Set the format string 


BR 


ERROR1 ; 


Print the error 


$ FETCH 


(R2)+,STS,R0 ; 


Set the STS returned 


$FETCH 


(R2) , STV,R0 


And the STV 


MOV 


#ERRSTR, Rl ; 


Set the error format string 


CALL 


PRINT ; 


Go edit and print the message 


JMP 


ERASE ; 


Let's try this again 


MOV 


#EDBLK , R2 ; 


Setup edit 


MOV 


#BUFFER, RO 


Output buffer 


CALL 


$EDMSG ; 


Exit the string 


MOV 


#BUFFER,Q. IOPL (R5) 




MOV 


R1,Q. IOPL+2 (R5) 




DIR$ 


R5 


Send to the terminal 


RETURN 




Return to caller 





. PSECT 


$DATA$,RW f D 


SYDSKA: 


. Asci i 


"SY: " 




SYDSKL 


= . - SYDSKA 


QUES: 


. Asci i 


<15><12>"File (s) to erase: " 




QUESL = 


. - QUES 


ERRSTR: 


.Asci z 


"$ERASE error — STS=%P, STV 


RSSST1: 


.Asci i 


"%N" 


RSSSTR: 


.Asci z 


" File %VA deleted" 
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NOFILE: 


. Asci z 


"%NNo files 


matching %VA%N" 


TTLSTR: 


. Asci z 


"%NTotal of 


%D files matching 




.EVEN 






FILCNT : 


.WORD 







EDBLK : 


.BLKW 


6 




BUFFER: 








BUFF: 


.Blkb 


128. 




EXPSTR: 


. BLKB 


128. 




RESSTR : 


.BLKB 


128 . 




IOSTAT: 


.WORD 







IOLEN: 


.WORD 







READ: 


QIOW$ 


IO.RLB, 1, 1, 


, IOSTAT 


WRITE: 


QIOW$ 


IO.WLB, 1, 1, 


, IOSTAT, , <, , 40> 




. END 


ERASE 





%VA deletedIN" 
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7.4 RENAME - $RENAME TEST 

The following shows how to build the RENAME program (Example 7-4) and 
shows a brief sample run of the program. 

MAC S Y : RENAME=LB : [1,1] RMSMAC/ML , SY : [uic] RENAME 

TKB 

TKB >S Y : RENAME/C P=SY: RENAME ,SY:GS A 
TKB>LB :SYSL IB/LB : INI DM : EXTSK 
TKB>LB: [1,1] RMS L IB/LB 
TKB>// 

RUN DB1: [200, 1] RENAME 
From: DES.TMP 
To: DES.XXX 

File DBO: [ 70 , 5 ] DES . TMP; 3 renamed to DBO : [ 70 , 5 ] DES . XXX; 3 
Total of 1 files matching DBO : [ 7 , 5 ] DES . TMP renamed 
From: ~z 
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Example 7-4: RENAME - $RENAME Test 



.TITLE RENAME - $RENAME TEST 

.IDENT /X01.00/ 

. ENABL LC 

. MCALL FAB$B,NAM$B,GSA$ 

. MCALL $ PARSE , $SEARCH , $RENAME , $STORE , $FETCH , $COMPARE 

. MCALL ALUN$S,QIOW$,DIR$,EXIT$S 



This program tests/demonstrates the use of 
the RMS-11 $RENAME function. 



RMS-11 Data Structures 



GSA$ 



GSA 



FAB 1 



FAB$B 
F$DNA 
F$DNS 
F$NAM 
F$LCH 
F$FOP 

FAB$E 



SYDSKA 
SYDSKL 
NAM1 
2. 

FB$F ID 



Old file name 
Default to SY: 

Link to NAM1 

Channel #2 

Turn on NAM usage 



NAM1 



NAM$B 
N$ESA 
N$ESS 
N$RSA 
N$RSS 

NAM$E 



ESSTR1 
128. 
RSSTR1 
128. 



NAM definition 
EXP STR address 
EXP STR length 
RES STR address 
RES STR length 



FAB2 



NAM 2 



FAB$B 
F$NAM 
F$LCH 

FAB$E 

NAM$B 
N$ESA 
N$ESS 

NAM$E 



NAM2 
2. 



ESSTR2 
128. 



New file name 
Link to NAM 2 
Same channel 



NAM definition 
EXP STR address 
EXP STR length 



RENAME: : 



. PSECT 


$CODE$,RO, I 




ALUN$S 


#1,#"TI,#0 


Assign the terminal 


MOV 


#FAB1,R0 , 


Map the target FAB 


MOV 


#EDBLK , R2 


• Map the exit block 


MOV 


#READ,R4 


Map the input DPB 


MOV 


#WRITE , R5 


Map the output DPB 


CLR 


Q.IOPL+4(R5) , 


Turn off carriage ctl 


MOV 


#QUES1, Q. IOPL (R5) 


MOV 


#QUES1L , Q. IOPL+2 (R5) 


DIR$ 


R5 


; Prompt for the DNA 


TSTB 


IOSTAT 


■ Check the IOSB 


BMI 


EXIT 


; Exit if error 


MOV 


#BUFF1,Q. IOPL (R4) 


MOV 


#64. / Q . IOPL+2 (R4) 
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EXIT 



DIR$ 
TSTB 
BMI 

$STORE 

$STORE 

$PARSE 

$COM PARE 

BLT 

MOV 

MOV 

MOV 

DIR$ 

TSTB 

BMI 

MOV 

MOV 

DIR$ 

TSTB 

BMI 

$STORE 

$STORE 

MOV 

CLR 

BR 



EXIT$S 



R4 

IOSTAT 
EXIT 

IOLEN,DNS,R0 
#BUFF1,DNA, RO 
RO 

#0,STS,R0 
ERROR 
#FAB2, RO 
#QUES2 , Q. IOPL (R5) 
#QUES2L,Q. IOPL+2 (R5) 



Get the response 
Check the IOSB 
Exit if error 
Set the default length 
Set the default address 
Parse the input spec 
An error? 
Yes if LT 
Map the 2d FAB 



R5 

IOSTAT 
EXIT 

#BUFF2 ,Q. IOPL (R4) 
#64. ,Q. IOPL+2 (R4) 
R4 

IOSTAT 
EXIT 

IOLEN,FNS,R0 
#BUFF2 , FNA , RO 
#40, Q. IOPL+4 (R5) 
FILCNT 
LOOP 



Prompt for the new name 
Check the IOSB 
Exit if error 



Get the response 
Check the IOSB 
Exit if error 
Set the default length 
Set the default address 
Restore carriage control 
Initialize file count 
Enter the RENAME loop 



Task exit 



LOOP: 



ERROR: 



MOV 
MOV 
MOV 
MOV 

$SEARCH 

$COMPARE 

BLT 

$FETCH 

$STORE 

$FETCH 

$STORE 

$RENAME 

$COM PARE 

BLT 

MOV 

CLR 

$FETCH 

TST 

$FETCH 
CLR 

$FETCH 
TST 

$FETCH 

MOV 

CALL 

INC 

BR 



#FAB1, RO 
#FAB2 , Rl 
#NAM1, R2 
#NAM2,R3 
RO 

#0,STS,R0 
SEAERR 
R4 ,RSA, R2 
R4,DNA,R1 
R4,RSL,R2 
R4 ,DNS,R1 
RO, , ,R1 

#0, STS,R0 
ERROR 
#EDBLK , RO 
(RO) 

(RO) ,RSL,R2 
(R0) + 

(RO) +,RSA,R2 
(RO) 

(RO) ,ESL,R3 
(R0) + 

(RO) ,ESA,R3 

#RENMSG,R1 

PRINT 

FILCNT 

LOOP 



MOV 

$FETCH 

$FETCH 

MOV 

CALL 

JMP 



#EDBLK,R2 
(R2) +,STS,R0 
(R2) ,STV, RO 
#ERRSTR, Rl 
PRINT 
RENAME 



Get the input FAB 
And the output FAB 
Setup NAM references 

Attempt to find a file 

Error? 

Yes if LT 

Get the resultant address 

Set this as default 

Get the resultant length 

Set the default length 

Rename input as output 

Error? 

Yes if LT- investigate 
Setup to show the rename 

Set the length 
Advance to next word 
Set the address 

Set the length 

Advance to next word 

Set te address 

Format string 

Display it 

Count the file 

And try another file 



Map the edit block 
Set the STS returned 
And the STV 

Set the error format string 
Go edit and print the message 
Let's try this again 



SEAERR: 
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SETES: 



TOTAL : 





N T~i T~) r*i \T w TTi OfTIO Ty C\ 

IfhKpNnr ,olo,KU , 


End of wild card search? 


BNE 


ERROR 


No if NE- show why 


MOV 


#EDBLK,R0 , 


Map the edit block 


TST 


F I LCNT 


Any files? 


BNE 


m m 7\ r 

1 U 1 AL , 


Yes if NE , show total 


MOV 


#NOF ILE , Rl 


Show the total 


LLK 


(RO) 




$FETCH 


(RO) , ESL,R2 , 


Set the length 


TST 


(R0) + 


• Advance 


!?r E 1CH 


( RO ) + t ESA , HZ , 


Get the ESA address 


CALL 


PRINT 






KHiNrtrlllj 


Kepea x. 


MOV 


FILCNT , (RO) + 


; Set the rename count 


MOV 


#TTLMSG, Rl 


Set the format string 


BR 


SETES 


; Add ESA and print 



PRINT : 



MOV 

MOV 

CALL 

MOV 

MOV 

DIR$ 

RETURN 



#EDBLK , R2 
#BUFFER, RO 
$EDMSG 
#BUFFER , WRITE +Q . IOPL 
Rl, WRITE+Q. IOPL+2 



Setup edit 
Output buffer 
Exit the string 



#WRITE 



Send to the terminal 
Return to caller 





.PSECT 


$DATA$, RW, D 


SYDSKA: 


. Asci i 


"SY: " 




SYDSKL 


= . - SYDSKA 


QUES1: 


.Asci i 


<15><12>"From: " 




QUES1L 


= . - QUES1 


QUES2: 


.Asci i 


<15><12>"To: 




QUES2L 


= . - QUES2 


ERRSTR: 


.Asci z 


"$RENAME error — STS=%P, STV 


RENMSG: 


. Asci z 


11 File %VA renamed to %VA" 


TTLMSG: 


.Asci z 


"%NTotal of %D files matching 


NOFILE: 


. Asci z 


"%NNo files matching %VA%N" 




.EVEN 




FILCNT: 


.WORD 





EDBLK: 


. BLKW 


6 


BUFFER: 






BUFFI: 


. BLKB 


64. 


BUFF2: 


. BLKB 


64 


ESSTR1: 


.BLKB 


128. 


ESSTR2: 


.BLKB 


128. 


RSSTR1: 


.BLKB 


128. 


IOSTAT: 


.WORD 





IOLEN: 


.WORD 





READ: 


QIOW$ 


IO.RLB, 1, 1, , IOSTAT 


WRITE: 


QIOW$ 


I 0. WLB, 1, 1, , IOSTAT, ,<, ,40> 




.END 


RENAME 
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7.5 GSA — CORE SPACE ALLOCATOR 



Example 7-5: GSA - Core Space Allocator 



.Title GSA - Core space allocator 
. Ident /V02.00/ 

.Enabl LC 



Copyright (C) 1982, Digital Equipment Corporation 

Maynard, Massachusetts 01754 

**-GSA - Dynamic memory allocation for RMS-11 pool 



Called by RMS-11 to manage pool space. 
In the event of pool exhaustion, the task 
image will be extended to obtain more space. 

May be called by user written code providing 
the interface standard is adhered to. 

Interface : 

Request space: 

R0 -> RMS/user Pool list head (maintained by RL/CQB) 

Rl := Amount of space requested (bytes) 

R2 := (differentiates between request and release) 

Release space: 

R0 -> RMS Pool list head (maintained by RL/CQB) 

Rl := Amount of space to be released (bytes) 

R2 -> Base address (for release) 



Returns : 

C-Bit "set" if an error has occurred (failure) 
C-Bit "clear" if no error has occurred (success) 



.Mcall Extk$S 
. Page 

.Sbttl Control block definitions 

.Psect GSA$$D,RW,D 



GSA internal data: 

GSABAS - Base address for the next memory allocation. 

Initially set to zero, it will be assigned 
the first address outside of the task's 
current address limits. 

GSAMIN - Decimal value reflecting the minimum size 
(in bytes) to extend the task in order to 
provide space to the pool. 

GSAREQ - Requested pool block number. If a request 
for the 'GSAMIN' fails, then the original 
allocation size will be attempted. If that 
fails, then there is no more memory left. 
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GSABAS : : 
GSAMIN: : 
GSAREQ: : 



.Word 
.Word 
.Word 



000000 
512. /64 
000000 



GSA base address 

(for next allocation) 

Minimum allocation 

(in 32-word blocks) 

Size of this request 

(if 1 GSAMIN 1 extends fail) 



. Page 

.Sbttl GSA Initialization code 
.Psect GSA$$I,RO,I 



GSA Initialization 

This code is entered when GSA is entered with GSABAS 
set to zero. In order to be able to build valid pool 
header tables, GSABAS must be properly initialized and 
maintained . 

Initialization consists of finding the size of the task 
in 32-word units, and converting that value to a usable 
16-bit address (which corresponds to the address of the 
next task extension (Extk$S) call. Once GSABAS has been 
initialized, GSAINI will not be reused. 



GSAINI : 



Mov 
Mov 
Mov 



R0,- (SP) 
R1,-(SP) 
R2,- (SP) 



RO-2 will be used to 
communicate with $INIDM 
NOTE : $INIDM uses EXTSK, 



The following code will use $INIDM to initialize the 
dynamic memory. As documented, Rl will return 
the first address following the task image, and R2 will 
return the size of the "free" memory from that address. 

NOTE: $INIDM and EXTSK reside in LB : [1,1] VMLIB for RSX 
systems, and in LB : SYSLIB for RSTS/E systems. 

$INIDM interface: 
Calls : 

R0 -> Pool list head 

Returns : 

R0 -> First address in task 
Rl -> First address AFTER task 

R2 := Size of free core after task (based at Rl) 



Call 

Mov 

Mov 

Mov 

Mov 

Return 



$INIDM 
Rl, GSABAS 
(SP) +,R2 
(SP) +,R1 
(SP) +,R0 



Initialize dynamic memory 
Setup the "free" address 
Restore the registers 



And return to GSA 



. Page 

.Sbttl GSA Mainline code 



.Psect GSA$$M,RO,I 
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GSA Mainline 



Entry point is "GSA", with registers 0-2 loaded as 
described above. 



GSA: : 



First, determine if dynamic memory has been initialized. 
GSABAS (initially set to zero) will be non-zero if $INIDM 
has been called and the memory list initialized. On RSX 
based systems it is possible to install tasks with an 
extension (/INCREMENT) . $INIDM will detect this and setup 
the first memory entry in the pool list. 

A point to note: If the RSX task has been installed with 
the non-checkpointable (/-CP) flag, then EXTKs will not 
return success. If it is necessary to install the task 
non-checkpointable, then the task should be installed with 
an increment value. 



Tst 
Bne 
Call 



GSABAS 
10$ 

GSAINI 



Dynamic memory initialized? 
Yes if NE, proceed 
Otherwise, initialize pool 



10$ 



Determine if this call involves real memory. 
Rl should contain the size (in bytes) of the core 
block requested or to be released. If zero then 
return to the caller without an error (TST leaves CC) . 



Tst 
Bne 

Return 



Rl 
20$ 



Real memory? 

Yes if NE, then process it 
Otherwise return with success 



20$ 



If this call is a request for space, pass control 
to the allocation routines. Otherwise, pass control 
to the system deallocation module $RLCB. There is 
no need to return, so control is passed via JMP. 
Note that module RQLCB resides in LB : [ 1 , 1 ] S YSL IB 
for RSX11M/M-PLUS and LB : SYSLIB for RSTS/E. 



Tst R2 

Beq 30$ 

Jmp $RLCB 

30$ : 



Address specified? (release) 
No if EQ, then it's a request 
Otherwise it's a release; do it 



Save our current context: 

R0 = Pool list head 

Rl = Size of memory required 

R2 = (signifies request) 



Mov R0,-(SP) 
Mov R1,-(SP) 
Mov R2,-(SP) 
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Attempt an allocation from the current pool 
If this is successful, pass control to the 
common exit. 



Call 
Bcc 



$RQCB 
70$ 



Try the allocation 
CC signifies success 



Now that the initial allocation failed, we must extend 
the task and give the new area (extended into) to the 
caller. To do this, the following procedure is used: 

1. The task is extended 

2. The area extended is returned to the 

pool specified as if a release was attempted 

3. We retry the allocation operation, but 
this time it should succeed, since we have 
increased the size of the pool area 

NOTE: $RQCB has a bad habit of nuking registers, so it 
becomes necessary to save and restore them around 
unsuccessful calls. 



Mov 



2 (SP) ,R1 



Obtain the request size 



Determine what the requirement is in 32-word blocks. 
Retain this value to allow GSA to decide whether 
to issue further task extension directives in 
order to satisfy the requirements. 



Add 


#63. ,R1 


Asr 


Rl 


Asr 


Rl 


Asr 


Rl 


Asr 


Rl 


Asr 


Rl 


Asr 


Rl 


Mov 


Rl , GSAREQ 



Round the request 
to a 32-word boundary 
Then convert the value 
to the number of 
32-word blocks. 



Save the real size 



We will allocate core to the pool in "reasonable" 
increments to cut down on system overhead, and pool 
fragmentation. This is accomplished by using either 
the requested size, or "GSAMIN", whichever is LARGER. 
If the request is unsuccessful, and the amount is 
smaller than GSAMIN, then request that particular size 



Cmp 
Bhi 
Mov 



Rl, GSAMIN 
40$ 

GSAMIN, Rl 



Smaller than minimum? 
No if HI, use it as is 
Otherwise use GSAMIN 



40$ 



Now we attempt to extend the task by that size. 
If the request fails, then use the size of the 
original request. If that also fails, then we 
simply ran out of memory. 



Extk$S Rl 



; Extend the task 
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50$: 



Bcc 


60$ 


; CC if successful 


Cmp 


Rl , GSAREQ 


; Is this request? 


Bios 


50$ 


; Yes if LOS , the end 


Mov 


GSAREQ , Rl 


; Otherwise try to use 


Br 


40$ 


; the actual request 


Sec 




; Mark failure 


Br 


70$ 


; And exit 



The task has been extended, now this memory must be 
released to the pool for future allocation. 
To do this, we setup the registers as if RMS were 
going to release the core, and call ourself to do 
the work. When the area has been released to the 
pool, we will return inline and proceed to reenter 
our code again from start to reattempt the allocation. 



60$: 



MOV 


4 (SP) ,R0 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Asl 


Rl 


Mov 


GSABAS , R2 


Add 


Rl , GSABAS 


Call 


GSA 



Setup the PLH 

Convert the real 

size to the actual 

16-bit size that 

was allocated. 

The virtual address 

should be after the 

task (which is now 

part of the task) 

Call ourself to release 



; At this point, the new 
? pool, and is available 
;: to allocate the memory 



memory has been added to the 
for use. We now reattempt 
required . 



Mov 
Mov 
Mov 
Br 



(SP) +,R2 
(SP) +,R1 
(SP) +, R0 
GSA 



Restore our registers 
to the initial state 
upon entry, and reenter 
as if it's a new request 



Common exit. Leave the registers in their current state, 
and return control to the caller. 



70$: 

Inc (SP)+ 

Bit (SP)+,(SP) + 

Return 



These won't alter the 
C-bit, so status remains 
unchanged upon return 



. End 
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COMPLETION CODES AND FATAL ERROR CODES 



Section A.l describes RMS-11 completions that are returned in the STS 
and STV fields of FABs and RABs . Section A. 2 describes RMS-11 fatal 
error completions. 



A.l COMPLETIONS RETURNED IN STS AND STV FIELDS 

This section lists and explains RMS-11 completions that are returned 
in the STS and STV fields of FABs and RABs. For each completion, the 
symbol, message, octal and decimal values, and explanation are given. 



SU$SUC Operation succeeded 



Octal: 000001 
Decimal: 1 



SU$DUP Inserted record has duplicate key 



Octal: 000002 
Decimal : 2 



The PUT or UPDATE operation inserted a record whose key 
duplicates a key already in the index. Note that this 
completion may also be returned if a duplicate of some key in 
the new or updated record ever existed in the file, even if 
that key has since been changed or the record deleted. 



SU$IDX Error updating index 



Octal: 000003 
Decimal: 3 



The PUT or UPDATE operation inserted the record properly, but 
RMS-11 did not optimize the index structure; subsequent 
retrievals of the record will require extra I/O operations. 



ER$ACC File access error 



Octal: 177740 
Decimal: -32 



1. A relative or indexed file is in the initial stage of 
creation and cannot be accessed yet. 2. A wri te-accessed 
file was not properly closed. 3. The file processor could 
not access the file. The STV field of the FAB contains the 
file processor error code; see your operating system 
documentation for the meaning of the code. 

If the STV field contains a 0, the creation (or block access 
copy) of the relative or indexed file never completed. If the 
STV field contains a nonzero value, that value is a system 
error code indicating the reason the access was rejected. 
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ER$ACT Activity precludes operation 



Octal: 177720 
Decimal : -48 



RMS-11 could not perform the requested operation because of an 
activity in progress (for example, RMS-11 cannot perform the 
CLOSE operation for a file that has an outstanding 
asynchronous operation) . 



ER$AID Bad value in AID field 



Octal : 
Decimal 



The file contains no area with the area number given 
AID field of an ALL block. 



ER$ALN Bad mask in ALN field 



Octal : 
Decimal 



177700 
-64 

n the 



177660 
-80 



The ALN field of an ALL block contains an invalid value. 



ER$ALQ Bad value in ALQ field 



Octal: 177640 
Decimal: -96 



The ALQ field of a FAB or an ALL block contains an invalid 
value; the value in the ALQ field is either too large, or is 
for an EXTEND operation. 



ER$ANI Bad ANSI-format magtape file 



Octal : 
Decimal 



177620 
-112 



The records in an ANSI-format magtape file are 
variable-length, but are not in the proper ANSI-D format. 



ER$AOP Bad mask in AOP field 



Octal : 
Decimal 



177600 
-128 



The AOP field of an ALL block contains an invalid mask value. 



ER$ATR Error reading attributes 



Octal: 177540 
Decimal: -160 



The file processor could not read the attributes for the file. 

The STV field of the FAB or RAB contains the file processor 

error code; see your operating system documentation for the 
meaning of the code. 



ER$ATW Error writing attributes 



Octal: 177520 
Decimal: -176 



The file processor could not write the attributes for the 
file. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$BKS Bad value in BKS field 



Octal : 
Decimal 



The value in the BKS field of the FAB is too large. 



ER$BKZ Bad value in BKZ field 



Octal : 
Decimal 



177500 
-192 



177460 
-208 



The value in the BKZ field of an ALL block is too large; or 
the bucket sizes of the lowest (LAN) and upper (IAN) areas of 
an index are not equal. 



A-2 



COMPLETION CODES AND FATAL ERROR CODES 



ER$BOF Beginning-of-f ile found 



Octal: 177430 
Decimal: -232 



The SPACE operation backspaced to the beginning-of-f i le . 



ER$BPA Bad address in BPA field 



Octal: 177420 
Decimal: -240 



The value in the BPA field of the FAB is odd, and the BPS 
field contains a nonzero value. 



ER$BPS Bad value in BPS field 



Octal: 177400 
Decimal : -256 



The value in the BPS field of the FAB is nonzero and not a 
multiple of 4, and the BPA field is nonzero. 



ER$CCR RAB already in use 



Octal: 177340 
Decimal: -288 



The CONNECT operation could not connect a stream using the 
specified RAB because the file is sequential and does not 
allow multiple connected streams. 



ER$CHG Illegal record key change 



Octal: 177320 
Decimal: -304 



The UPDATE operation did not allow a changed record key 
because the index does not allow key changes or does not allow 
duplicate key values. 



ER$CHK Bad bucket header 



Octal: 177300 
Decimal: -320 



The bucket header data for an indexed file is corrupted. 

Notify your system manager, who should follow this procedure 
to recover from the error: 



1. Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

2. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step . 



3. Restore the file from a backup copy. 



ER$CLS File processor error Octal: 177260 

Decimal: -336 

The file processor returned an error condition to the CLOSE 
operation. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

ER$COD Bad code in COD field Octal: 177240 

Decimal: -352 



The value in the COD field of an XAB is not valid. 
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ER$CRE File processor error 



Octal: 177220 
Decimal : -368 



The file processor returned an error condition to the CREATE 
operation. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$CUR Undefined current-record context 



Octal: 177200 
Decimal: -384 



A DELETE , TRUNCATE , or UPDATE operation required a 
current-record context, but it was undefined. 



def ined 



ER$DAN Bad value in DAN field 



Octal: 177140 
Decimal : -416 



The value in the 
nonexistent area. 



DAN field of a KEY block specifies a 



ER$DEL Record having RFA deleted 



Octal : 
Decimal 



177120 
-432 



The record specified by RFA has been deleted. 
ER$DEV Bad device specification 



Octal: 177100 
Decimal: -448 



The device specification given contains a syntax error, there 
is no such device, the device is inappropriate for the 
operation, or two different devices have been specified for a 
RENAME operation. 



ER$DFW File processor error 



Octal: 177070 
Decimal : -456 



The file processor returned an error while writing 
def erred-wr i te data. The STV field of the FAB or RAB contains 
the file processor error code; see your operating system 
documentation for the meaning of the code. 



ER$DIR Bad directory specification 



Octal : 
Decimal 



177060 
-464 



The directory specification contains a syntax error. 



ER$DME Pool exhausted 



Octal : 
Decimal 



177040 
-480 



One of the five pools that RMS-11 uses cannot provide 
space for the operation. 



ER$DNA Bad address in DNA field 



Octal : 
Decimal : 



needed 



177030 
-488 



The DNA field of the FAB contains 0, but the DNS field is 
nonzero . 



ER$DNF No such directory 



Octal: 177020 
Decimal : -496 



The directory specification given specifies a 
d i rectory . 



nonexistent 
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ER$DNR Device not ready 

The device specified is not on line. 
ER$DPE Device positioning error 



ER$ESS 



Octal: 177000 
Decimal : -512 



Octal: 176770 
Decimal: -520 



The file processor could not position the magtape device as 
specified. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$DTP Bad code in DTP field 



Octal: 176760 
Decimal: -528 



The value in the DTP field of a KEY block does not specify a 
valid key data type. 



ER$DUP Duplicate key not allowed 



Octal: 176740 
Decimal: -544 



The record offered for insertion had a record key that would 
duplicate a record already in the index, but the index does 
not allow duplicate keys. 



ER$ENT File processor error 



Octal : 
Decimal 



176720 
-560 



The file processor could not create the specified directory 

entry. The STV field of the FAB contains the file processor 

error code; see your operating system documentation for the 
meaning of the code. 



ER$ENV Feature not in selected RMS-11 environment 



Octal : 
Decimal 



176700 
-576 



The RMS-11 environment (selected with the ORG$ macro or by the 
compiler or by the manner in which RMS-11 code is linked with 
your program) does not include the attempted operation for the 
specified file organization. 



ER$EOF End-of-file reached 



Octal: 176660 
Decimal: -592 



The operation specified a record or block that is past the 
last record or block. 



ER$ESA Bad address in ESA field 

The ESA field of the NAM block contains 0. 
ER$ESL Bad value in ESL field 



The ESL field of the NAM block contains 0. 
ESS field value too small 



Octal : 
Decimal 



Octal : 
Decimal 



Octal : 
Decimal : 



176650 
-600 



176644 
-604 



176640 
-608 



The value in the ESS field of the NAM block specifies an 
expanded string buffer that is too small to contain the 
expanded string. 
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ER$EXP File expiration date not yet reached Octal: 176630 

Decimal : -616 



ER$EXT File processor error Octal: 176620 

Decimal : -624 

The file processor could not make the requested extension to 
the file. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 

ER$FAC FAC field forbids operation Octal: 176560 

Decimal : -656 

The attempted record or block operation was not specified in 
the FAC field of the FAB when the file was created or opened. 

ER$FAL Operation not supported by remote node Octal: 176550 

Decimal : -664 

The remote node for a remote RMS-11 operation does not support 
that operation. The STV field of the FAB or RAB contains (in 
its high 4 bits) a code that gives the reason for the error: 

• 0--lncompatible operating systems; the low 12 bits of the 
STV field contain the type of the remote operating system 

• 1 — Incompatible file systems; the low 12 bits of the STV 
field contain the type of the remote file system 

• 2--DAP version number smaller than 5; the low 12 bits of 
the STV field contain the DAP version number 

• 3 — DAP modification number smaller than 6; the low 12 bits 
of the STV field contain the DAP modification number 

• 4 — Unsupported file organization 

• 5--Unsupported record access 

• 6--Operation not supported by FAL; the low 12 bits of the 
STV field contain the operation code 

• 7--Remote I/O buffer too small; the low 12 bits contain 
the size of the remote I/O buffer 

ER$FEX File already exists Octal: 176540 

Decimal: -672 

The file specified for creation already exists, but 
supersession was not specified. 

ER$FID Bad value in FID field Octal: 177530 

Decimal: -680 

The FID field of the NAM block contains a value that is not a 
f i le ident i f ier . 

ER$FLG Bad mask in FLG field Octal: 176520 

Decimal: -688 

The combination of masks specified in the FLG field of a KEY 
block is illegal. 
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ER$FLK File locked by another task 



Octal: 176500 
Decimal: -704 



The file sharing specified is not allowed by a task already 
accessing the file. 



ER$FNA Bad address in FNA field 



Octal: 176470 
Decimal: -712 



The FNA field of the FAB contains 0, but the FNS 
nonzero . 



field 



is 



ER$FND File processor error 



Octal: 176460 
Decimal: -720 



The file processor could not find the file specified. The STV 

field of the FAB contains the file processor error code; see 

your operating system documentation for the meaning of the 
code . 



ER$FNF File not found 



Octal: 176440 
Decimal: -736 



The file specified for a directory or file operation does not 
ex ist . 



ER$FNM Bad file name 



Octal: 176420 
Decimal: -752 



The file name portion of a file specification string has a 
syntax error. 



ER$FOP Bad mask in FOP field 



Octal: 176400 
Decimal: -768 



The FOP field of the FAB contains one or more illegal masks. 



ER$FUL Device or file full 



Octal: 176360 
Decimal: -784 



The specified device or file has 
creation or extension. 



no 



room to allow file 



ER$IAN Bad value in IAN field 



Octal: 176340 
Decimal: -800 



The value in the IAN 
nonexistent file area. 



field of a KEY block specifies a 



ER$IDX Index not initialized 



Octal: 176320 
Decimal: -816 



This code is only returned in the STV field of the RAB in 
conjunction with the code ER$RNF in the STS field. It 
indicates that no entries have been made in the index 
specified for the GET or FIND operation. 



ER$IFI Bad value in IFI field 



Octal: 176300 
Decimal: -832 



The value in the IFI field of the FAB is not the internal file 
identifier for a file. 
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ER$IMX Too many XABs of same type 



Octal: 176260 
Decimal: -848 



The number of XABs of the same type in the chain of XABs is 
too large (more than 254 ALL blocks or KEY blocks, more than 1 
DAT block, PRO block, or SUM block). 



ER$IOP Illegal operation for file 



Octal: 176220 
Decimal: -880 



The requested operation is illegal for the file organization 
or for the allowed access. 



ER$IRC Illegal record found in sequential file 



Octal: 176200 
Decimal: -896 



The record length field of a record in a sequential file is 
inval id . 



ER$ISI Bad value in ISI field 



The ISI field of the RAB contains 
internal stream identifier. 

ER$KBF Bad address in KBF field 



The KBF field of the RAB contains 0. 
ER$KEY Bad key 



Octal: 176160 
Decimal: -912 

value that is not an 



Octal : 
Decimal 



Octal : 
Decimal 



176140 
-928 



176120 
-944 



The key specified for a key access operation is invalid 
(either a negative RRN or an erroneous packed-decimal key) . 



ER$KRF Bad value in KRF field 



Octal: 176100 
Decimal: -960 



The KRF field of the RAB contains (or contained) a value that 
does not specify a file index. For a key access FIND or GET 
operation, the RAB contains the invalid value in its KRF 
field; for a sequential access FIND or GET operation, the RAB 
contained the invalid value in its KRF field during an earlier 
CONNECT or REWIND operation. 



ER$KSZ Bad value in KSZ field 



Octal : 
Decimal 



176060 
-976 



The KSZ field of the RAB contains an invalid value. 



Octal : 
Decimal 



176040 
-992 



ER$LAN Bad value in LAN field 

The value in the LAN field of a KEY block specifies a 
nonexistent file area. 

ER$LBL Bad magtape label 

The magtape does not have a valid ANSI label. 



Octal : 
Decimal 



176020 
-1008 
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ER$LBY Logical channel busy 

The LCH field of the FAB contains the number 
channel that is already in use by the task. 

ER$LCH Bad value in LCH field 



Octal : 
Decimal 



176000 
-1024 



of a logical 



Octal: 175760 
Decimal: -1040 



The LCH field of the FAB contains a value that is too large to 
be a logical channel number. 



ER$LEX Extension not needed 



The requested extension was not needed because 
still contains an unused extent. 



Octal: 175750 
Decimal: -1048 

the file area 



ER$LOC Bad value in LOC field 



Octal: 175740 
Decimal: -1056 



The LOC field of an ALL block contains a value that 
specify a valid location. 



does not 



ER$MEM Memory address rollover 



The area specified for the file & u 
expanded string, or resultant string ex 
addressable memory. 

ER$MKD File processor error 



Octal: 175710 
Decimal: -1080 

string, default string, 
tends beyond the end of 



Octal: 175700 
Decimal: -1088 



The file processor could not mark the specified file for 
deletion. The STV field of the FAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$MRN Bad value in MRN field or bad record number 



Octal: 175660 
Decimal: -1104 



The MRN field of the FAB contains a negative number (CREATE 

operation), or the record number specified for a key access 

record operation is larger than the file maximum record number 

(specified in the MRN field at file creation). 



ER$MRS Bad value in MRS field 



Octal: 175640 
Decimal: -1120 



The MRS field of the FAB contains even though the file to be 
created is requested either to be a relative file or to have 
fixed-length records. 
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ER$NAE Dnmappable network access error 



Octal : 
Decimal 



175630 
-1128 



error 



If this error occurs, please submit a Software Performance 
Report to DIGITAL, including the following information: 

• Contents of general registers and stack 

• Operation and file organization for which the 
occurred 



• Task builder map of the task 

• Post-mortem dump 
ER$NAM Bad address in NAM field 



Octal : 
Decimal 



The NAM field of the FAB contains or an odd address. 



ER$NEF Context not end-of-file 



Octal : 
Decimal 



175620 
-1136 



175600 
-1152 



The PUT operation could not insert a record into a sequential 
file because the next-record context was not the end-of-file. 



ER$NET Network link lost 



The STV field of the FAB or RAB contains 
code . 

ER$NMF No more matching files 



Octal: 175570 
Decimal: -1160 

the network error 



Octal: 175554 
Decimal: -1172 



The SEARCH operation ended the wildcard SEARCH series because 
there are no more files matching the wildcard file 
specification. 



ER$NOD Bad node name 



Octal: 175550 
Decimal: -1176 



The specified node name is invalid or, for the RENAME 
operation, the two node names are different. 



ER$NPK No primary key for indexed file 



Octal : 
Decimal 



175540 
-1184 



The CREATE operation did not create the specified file because 
no primary index was specified even though the request 
specified indexed file organization. 



ER$ORD Ordering of XABs illegal 

The chain of XABs for 
improperly ordered. 

ER$ORG Bad mask in ORG field 



Octal: 175500 
Decimal: -1216 

directory or file operation is 



Octal: 175460 
Decimal: -1232 



The ORG field of the FAB contains an invalid file organization 
code; the file was not created. 
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ER$PLG Error reading file prologue 



Octal: 175440 
Decimal: -1248 



The data read from the file prologue is incorrect. 

Notify your system manager, who should follow this procedure 
to recover from the error: 



Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step . 



3. Restore the file from a backup copy. 
ER$PLV File prologue version level unsupported 



Octal : 
Decimal 



175430 
-1256 



The file prologue version number shows that the file was 
created by a version of RMS that is not supported on your 
system . 



ER$POS Bad value in POS field 



Octal : 
Decimal 



175420 
-1264 



The POS field of a KEY block contains a value that is greater 
than the maximum record size for the file; the STV field of 
the FAB contains the address of the KEY block. 



ER$PRM Bad file date read 

The file dates read are illegal. 
ER$PRV Privilege violation 



Octal: 175400 
Decimal: -1280 



Octal: 175360 
Decimal: -1296 



The file processor denied the requested operation because the 
task has no privilege for the operation. 



ER$RAC Bad mask in RAC field 



Octal : 
Decimal 



The RAC field of the RAB contains an illegal value. 



ER$RAT Bad mask in RAT field 



Octal : 
Decimal 



The RAT field of the FAB contains illegal set bits. 



ER$RBF Bad address in RBF field 



Octal : 
Decimal 



175320 
-1328 



175300 
-1344 



175260 
-1360 



The RBF field of the RAB contains an odd address; the address 
must be even for block access. 
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ER$RER File processor error 



Octal: 175240 
Decimal: -1376 



The file processor could not read the requested record or 
block. The STV field of the FAB or RAB contains the file 
processor error code; see your operating system documentation 
for the meaning of the code. 



ER$REX Record already exists 



Octal: 175220 
Decimal: -1392 



The target cell for a PUT operation to a relative file already 
contains a record. 



ER$RFA Bad value in RFA field 



Octal : 
Decimal 



175200 
-1408 



The RFA field of the RAB contains an illegal RFA. 



ER$RFM Bad code in RFM field 



Octal : 
Decimal 



175160 
-1424 



The RFM field of the FAB contains an illegal value. 



ER$RLK Record locked 



Octal : 
Decimal 



175140 
-1440 



The bucket containing the specified record is locked by 
another task or by another stream in your task. 



ER$RMV File processor error 



Octal: 175120 
Decimal : -1456 



The file processor could not delete the specified directory 
entry. The STV field of the FAB contains the file processor 
error code; see your operating system documentation for the 
meaning of the code. 



ER$RNF No such record 



Octal : 
Decimal 



175100 
-1472 



The record specified for key access does not exist. 



ER$RNL Record not locked 



Octal : 
Decimal 



175060 
-1488 



The FREE operation found that no record was locked for the 
stream . 



ER$ROP Bad mask in ROP field 



Octal : 
Decimal 



175040 
-1504 



The ROP field of the RAB contained illegal set bits. 
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ER$RPL File processor error 



Octal: 175020 
Decimal: -1520 



The data read from the file prologue is incorrect. 

Notify your system manager, who should follow this procedure 
to recover from the error: 

1. Move the disk to a different drive and try the process 
again. If the process succeeds, the error was a hardware 
error; report the faulty hardware and continue 
processing. If the process fails again, proceed to the 
next step. 

2. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step . 



3. Restore the file from a backup copy. 
ER$RRV Bad internal pointer 



Octal : 
Decimal : 



An internal pointer in the file is invalid. Reload the 
with RMSCNV or RMSIFL, using its primary index. 



ER$RSL Bad value in RSL field 

The RSL field of the NAM block contains 0. 
ER$RSS Bad value in RSS field 



Octal : 
Decimal : 



Octal : 
Decimal 



175000 
-1536 

file, 



174754 
-1556 



174750 
-1560 



The RSS field of the NAM block contains 
ER$RST Bad address in RSA field 



ER$RSZ 



The RSA field of the NAM block contains 
Bad value in RSZ field 



Octal : 
Decimal 



Octal : 
Decimal 



174744 
-1564 



174740 
-1568 



The RSZ field of the RAB contains a value that is larger than 
the maximum allowed record size, or (for fixed-length records) 
is not equal to the maximum record size, or (for an UPDATE 
operation to a sequential file) is not equal to the length of 
the record to be updated. 



ER$RTB Record too big for user buffer 



Octal: 174720 
Decimal: -1584 



The record read cannot fit into the user buffer; the STV 

field of the RAB contains the size of the record, and the 

portion that will fit is moved to the user buffer as for a 
successful GET. 
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ER$RVU Internal pointer corrupted 



ER$SEQ 



Octal: 174710 
Decimal: -1592 



The record insertion succeeded and the primary index was 
updated successfully; however, RMS-11 could not update 
internal pointers. 

To recover from the error, follow this procedure: 

1. Recreate the file using an RMS-11 utility (RMSIFL or 
RMSCNV) . If this succeeds, the primary index and data 
records were free of errors and the new file is valid; 
continue processing. If this fails, proceed to the next 
step . 



2. Restore the file from a backup copy. 
Sequential insertion records not in order 



Octal : 
Decimal : 



174700 
-1600 



The sequential access PUT operation found records whose 
primary keys were not in ascending order. 



ER$SHR Bad mask in SHR field 



Octal : 
Decimal : 



The SHR field of the FAB contains an illegal mask. 



ER$SIZ Bad value in SIZ field 



Octal : 
Decimal 



174660 
-1616 



174640 
-1632 



ER$SYS 



The SIZ field of a KEY block contains an illegal value. 



ER$SUP Operation not supported over network 



Octal : 
Decimal 



174610 
-1656 



The requested operation is not supported over the network. 
System error 



Octal : 
Decimal 



174600 
-1664 



The interface between RMS-11 and the system is in error; the 
STV field of the FAB or RAB contains the status code for a 
system directive. Please submit a Software Performance 
Report . 



ER$TRE Index error 



Octal: 174560 
Decimal: -1680 



The index contains invalid data. Build a new file using 
either an RMS-11 utility (RMSIFL or RMSCNV) or using 
sequential access and the primary index to fetch the old 
records . 



ER$TYP Bad file type 



Octal: 174540 
Decimal: -1696 



The file type in a file specification contains invalid syntax. 



ER$UBF Bad address in OBF field 



Octal: 174520 
Decimal: -1712 



The UBF field of the RAB contains or, for block access, an 
odd address. 
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ER$UIN Field value rejected by FAL 



Octal: 174510 
Decimal: -1720 



The FAL (file access listener) rejected the value in a control 
block field; the STV field of the FAB or RAB contains a code 
showing which field. See your DECnet documentation for the 
meanings of these codes. 



ER$USZ Bad value in USZ field 

The USZ field of the RAB contains 0. 
ER$VER Bad file version number 



Octal : 
Decimal 



Octal : 
Decimal 



174500 
-1728 



174460 
-1744 



The file version portion of a file specification contains a 
syntax error. 



ER$WCD Illegal wildcard in merged string 



Octal: 174430 
Decimal: -1768 



The merged string contains a wildcard character, but 
wildcarding is not in progress or is illegal for the 
operat i on . 



ER$WER File processor error 



Octal: 174420 
Decimal: -1776 



The file processor could not write to the file. The STV field 
of the FAB or RAB contains the file processor error code; see 
your operating system documentation for the meaning of the 
code . 



ER$WLK Device write-locked 

The device specified is write-locked. 
ER$WPL File processor error 



Octal : 
Decimal 



Octal : 
Decimal 



174410 
-1784 



174400 
-1792 



The file processor could not write the file prologue. The STV 
field of the FAB or RAB contains the file processor error 
code; see your operating system documentation for the meaning 
of the code. 



ER$XAB Bad address in XAB field 



Octal : 
Decimal 



The XAB field of the FAB contains an odd address. 



ER$XTR Extraneous data in file specification 



Octal : 
Decimal 



174360 
-1808 



174340 
-1824 



The file specification contains extraneous characters. The 
value in the STV field of the FAB is the address of the first 
character beyond the end of the valid file specification. 
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A. 2 FATAL ERROR COMPLETIONS 

This section lists and explains RMS-11 completions that are returned 
in general register RO. These errors are fatal either because RMS-11 
detected an internal error condition and could not continue, or 
because the RAB or FAB is of questionable validity and RMS-11 
therefore did not write the completion in its fields. 



ER$ACT Illegal concurrent operation 



Octal: 177720 
Decimal : -48 



1. The FAB you specified is already in use by another 
operation. 2. You have illegally interrupted RMS-11 
process i ng . 



ER$AST Illegal operation at AST level 



Octal: 177560 
Decimal : -144 



Your program attempted to use WAIT operation at AST level. 



ER$BUG Error in RMS-11 internal data 



Octal : 
Decimal 



177360 
-272 



RMS-11 detected an error in its internal data structures. The 
error may have been caused by your task writing into the 
structures; if you think your task did not cause the error, 
please submit a Software Performance Report to DIGITAL, 
including the following information: 

• Contents of general registers and stack 



Operation 
occurred 



and file organization for which the error 



ER$CPB 



• Task builder map of the task 

• Post-mortem dump 
Bad parameter block 



Octal : 
Decimal : 



177230 
-360 



The parameter block (pointed to by R5) for an operation macro 
has an invalid argument count or is at a zero or odd address. 



ER$FAB Bad FAB 



Octal: 176600 
Decimal : -640 



The value in the BID or BLN field of the specified FAB is not 
the correct identifier or block length for a FAB, or the 
address of the FAB is or odd. 



ER$LIB Resident library not available 



Octal: 175744 
Decimal: -1052 



The version of the RMS-11 resident library needed for your 
task is not available. 
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ER$MAP 



Error in internal buffer mapping data 



Octal : 
Decimal : 



175720 
-1072 



RMS-11 detected an error in its internal data structures. The 
error may have been caused by your task writing into the 
structures; if you think your task did not cause the error, 
please submit a Software Performance Report to DIGITAL , 
including the following information: 

• Contents of general registers and stack 

• Operation and file organization for which the error 
occurred 

• Task builder map of the task 

• Post-mortem dump 



The value in the BID or BLN field of the specified RAB is not 
the correct identifier or block length for a RAB, or the 
address of the RAB is or odd. 



ER$RAB 



Bad RAB 



Octal : 
Decimal : 



175340 
-1312 
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RMS-11 macros detect some errors during assembly. For each such 
error,. the macro issues a . PRINT or .ERROR assembler directive with a 
message. This appendix shows these messages and their meanings. 



$COMPARE MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $COMPARE macro. 

$COMPARE MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $COMPARE macro. 

$FETCH MACRO - PC DESTINATION INVALID 

You cannot specify the PC as the destination for the $FETCH 
macro . 

$FETCH OR $STORE MACRO - ADDRESS MODE INVALID 

You have used an illegal address mode in the source for a $STORE 
macro or in the destination for a $FETCH macro. See Chapter 3 
for a description of legal address modes for these macros. 

$FETCH OR $STORE MACRO - FIELD PARAMETER INVALID 

You can specify only a valid field mnemonic as the field 
parameter for a field access macro. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR GIVEN REGISTERS 

You cannot specify the given register as the source or 
destination address because the field is larger than the 
remaining registers. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR IMMEDIATE MODE 

You can specify an immediate mode value for a field access macro 
only if you specify a 1-byte or 1-word field. 

$FETCH OR $STORE MACRO - FIELD TOO LARGE FOR REGISTERS 

You cannot specify a register as the source or destination 
address because the given field is too large. 
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$FETCH OR $STORE MACRO - REGISTER PARAMETER INVALID 

You can specify only RO, Rl, R2 , R3, R4, or R5 as the register 
parameter for a field access macro. 

$FETCH OR $STORE MACRO - REGISTER USAGES OVERLAP 

You cannot specify the given register as the source or 
destination address because the indicated registers overlap the 
register containing the control block address. 

$OFF MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word 
parameter for the $OFF macro. 

$OFF MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as 
for the $OFF macro. 

$SET MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word 
parameter for the $SET macro. 

$SET MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $SET macro. 

$SETGSA MACRO - REGISTER PARAMETER INVALID 

You must specify RO, Rl, R2, R3, R4, or R5 as the register 
parameter for the $SETGSA macro. 

$TESTBITS MACRO - FIELD TOO LARGE 

You can specify only a 1-byte or 1-word field as the field 
parameter for the $TESTB ITS macro. 

$TESTB ITS MACRO - FIELD PARAMETER INVALID 

You must specify a valid field mnemonic as the field parameter 
for the $TESTBITS macro. 

F$BSZ MACRO - BSZ FIELD NOT USED IN RMS-11 

RMS-11 has no BSZ field in the FAB; therefore the F$BSZ macro 
cannot initialize the field. 

F$ JFN MACRO - JFN FIELD NOT USED IN RMS-11 

RMS-11 has no JFN field in the FAB; therefore the F$ JFN macro 
cannot initialize the field. 

FAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the FAB$B macro to begin FAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro) . 

FAB$B MACRO - FAB NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the FAB$B macro; this 
assures word-alignment for the FAB. 



field as the field 



the field parameter 



field as the field 
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FAB$E MACRO - NOT IN FAB DECLARATION 

You must begin a FAB declaration with the FAB$B macro before 
ending it with a FAB$E macro. 

NAM$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the NAM$B macro to begin NAM block declaration 
until you have ended the current block or pool declaration (using 
the FAB$E , NAM$E, POOL$E, RAB$E or XAB$E macro) . 

NAM$B MACRO - NAM BLOCK NOT WORD-ALIGNED 

Use the . EVEN assembler directive before the NAM$B macro; this 
assures word-alignment for the NAM. 

NAM$E MACRO - NOT IN NAM BLOCK DECLARATION 

You must begin a NAM block declaration with the NAM$B macro 
before ending it with a NAM$E macro. 

OPERATION MACRO - FAB OR RAB ADDRESS PARAMETER MISSING 

You must specify a control block address for the operation macro; 
for a file operation, specify a FAB address; for a stream, 
record, or block I/O operation, specify a RAB address. 

ORG$ MACRO - OPERATION PARAMETER INVALID 

You can specify only CRE, DEL, FIN, GET, PUT, and UPD as 
operation parameters for the ORG$ macro. 

ORG$ MACRO - ORGANIZATION PARAMETER INVALID 

You can specify only IDX, REL, or SEQ as the organization 
parameter for the ORG$ macro. 

ORG$ MACRO - ORGANIZATION PARAMETER MISSING 

You must specify IDX, REL, or SEQ as the organization parameter 
for the ORG$ macro. 

POOL$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the POOL$B macro to begin pool declaration until 
you have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro) . 

POOL$E MACRO - NOT IN POOL DECLARATION 

You must begin a POOL declaration with the POOL$B macro before 
ending it with a POOL$E macro. 

R$LSN MACRO - LSN FIELD NOT USED IN RMS-11 

RMS-11 has no LSN field in the RAB; therefore the R$LSN macro 
cannot initialize the field. 

RAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the RAB$B macro to begin RAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E, NAM$E, POOL$E, RAB$E or XAB$E macro). 
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RAB$B MACRO - RAB NOT WORD -ALIGNED 

Use the . EVEN assembler directive before the RAB$B macro; this 
assures word-alignment for the RAB. 

RAB$B MACRO - RAB TYPE PARAMETER INVALID 

You can specify only SYN, AS YN , or a null as the parameter for 
the RAB$B macro. 

RAB$E MACRO - NOT IN RAB DECLARATION 

You must begin a RAB declaration with the RAB$B macro before 
ending it with a RAB$E macro. 

X$SIZ MACRO - TOTAL KEY SIZE TOO LARGE 

The sum of the segment sizes for a key is greater than 255. 
Specify smaller segments. 

XAB$B MACRO - ALREADY IN BLOCK OR POOL DECLARATION 

You cannot use the XAB$B macro to begin XAB declaration until you 
have ended the current block or pool declaration (using the 
FAB$E , NAM$E, POOL$E, RAB$E or XAB$E macro) . 

XAB$B MACRO - XAB NOT WORD-ALIGNED 

Use the .EVEN assembler directive before the XAB$B macro; this 
assures word-alignment for the XAB. 

XAB$B MACRO - XAB TYPE PARAMETER INVALID 

You can specify only XB$ALL , XB$DAT , XB$KEY, XB$PRO, or XB$SUM as 
the XAB type parameter for the XAB$B macro. 

XAB$E MACRO - NOT IN XAB DECLARATION 

You must begin a XAB declaration with the XAB$B macro before 
ending it with a XAB$E macro. 
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MACROS THAT DECLARE SYMBOLS AND OTHER MACROS 



Table C-l lists RMS-11 macros (and their arguments) that declare 
symbols and other macros. In the table, the expression xxx represents 
a 2- or 3-character string, so that the expression 0$xxx represents 
all symbols that begin with 0$; the expression fid represents a field 
mnemonic . 

Note that you can declare symbols either globally or locally. For a 
FAB$BT, RAB$BT, XAB$BT, or $RMSTAT macro, give the argument DFIN$G (or 
omit the argument) to define symbols globally; give the argument 
DFIN$L to define symbols locally. 

Note also that you can declare symbols for control block sizes without 
declaring field-offset symbols. For a FAB0F$, NAM0F$, RAB0F$, XAB0F$, 
XBA0F$, XBD0F$, XBK0F$, XBP0F$ , or XBS0F$ macro, give the argument 
DEF$SZ to define only symbols for block sizes, or give no argument to 
define both symbols for block sizes and field-offset symbols. 



Table C-l: Macros That Declare Symbols and Other Macros 



Macro Argument Declares 



FAB $B 



FAB$BT 

FAB$BT 
FAB0F$ 
FAB0F$ 



DFIN$G 



DFIN$L 



DEF$SZ 



- FAB field-initialization macros: of the form 
F$f Id 

- FAB end-block-declaration macro: FAB$E 

- FAB field-offset symbols: of the form 0$fld 

- FAB code and mask symbols: of the form 
FB$xxx 

- Global FAB code and mask symbols: of the 
form FB$xxx (except FAB length symbol 
FB$BLN) 

- Local FAB code and mask symbols: of the form 
FB$xxx (except FAB length symbol FB$BLN) 

- FAB field offset symbols: of the form 0$fld 

- FAB length symbol: FB$BLN 

- FAB length symbol: FB$BLN 



(Continued on next page) 
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MACROS THAT DECLARE SYMBOLS AND OTHER MACROS 

Table C-l (Cont.)i Macros That Declare Symbols and Other Macros 



Macro 



Argument Declares 



$FBCAL 



$GNCAL 



NAM$B 



NAMOF$ 

NAMOF$ 
POOL$B 

RAB$B 



RAB$BT 



RAB$BT 



RABOF$ 



RABOF$ 



DEF$SZ 



DFIN$G 



DFIN$L 



- Directory operation macros: $ENTER, $PARSE , 
$REMOVE , $RENAME , and $SEARCH 

- File operation macros: $CLOSE, $CREATE , 
$DISPLAY / $ERASE, $EXTEND, and $OPEN 

- Get-space address macros: GSA$ , $GETGSA , and 
$SETGSA 

- Facilities-declaration macro: ORG$ 

- RMS-11 initialization macros: $INIT and 
$INITIF (obsolete) 

- Field-access macros: $COMPARE, $FETCH , $OFF , 
$SET, $STORE, and $TESTBITS 

- Completion-handler return macro: $RETURN 

- NAM block field-initialization macros: of 
the form N$fld 

- NAM block end-block-declaration macro: NAM$E 

- NAM block field-offset symbols: of the form 
0$f Id 

- NAM block code and mask symbols: of the form 
NB$xxx 

- NAM block field offset symbols: of the form 
0$f Id 

- NAM block length symbol: NB$BLN 



- NAM block length symbol: NB$BLN 

- Pool declaration macros: P$BDB, 
P$FAB , P$IDX, P$RAB , and P$RABX 

- End-pool-declaration macro: POOL$E 



P$BUF, 



DEF$SZ 



- RAB field-initialization macros: of the form 
R$f Id 

- RAB end-block-declaration macro: RAB$E 

- RAB field-offset symbols: of the form 0$fld 

- RAB code and mask symbols: of the form 
RB$xxx 

- Global RAB code and mask symbols: of the 
form RB$xxx (except RAB length symbol RB$BLN 
or RB$BLL) 

- Local RAB code and mask symbols: of the form 
RB$xxx (except RAB length symbol RB$BLN or 
RB$BLL) 

- RAB field offset symbols: of the form 0$fld 

- RAB length symbol: RB$BLN (for synchronous 
RAB) or RB$BLL (for asynchronous RAB) 

- RAB length symbol: RB$BLN (for synchronous 
RAB) or RB$BLL (for asynchronous RAB) 



(Continued on next page) 
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MACROS THAT DECLARE SYMBOLS AND OTHER MACROS 
Table C-l (Cont.)s Macros That Declare Symbols and Other Macros 



Macro Argument Declares 



$RBCAL 



$RMSTAT DFIN$G 



- Stream operation macros: $CONNECT, 
$DISCONNECT, $FLUSH, $FREE, $NXTVOL, 
$REWIND , and $WAIT 

- Record operation macros: $DELETE / $F IND , 
$GET , $PUT, $TRUNCATE, and $UPDATE 

- Block operation macros: $READ, $SPACE, and 
$WRITE 

- Global completion symbols: of the forms 
ER$xxx and SU$xxx 



$RMSTAT DFIN$L 



- Local completion symbols: of the 
ER$xxx and SU$xxx 



forms 



XAB$B XB$ALL 



XAB$B XB$DAT 



XAB$B XB$KEY 



XAB$B XB$PRO 



XAB$B XB$SUM 



- ALL block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- ALL block field-offset symbols: of the form 
0$f Id 

- XAB code and mask symbols : of the form 
XB$xxx 

- DAT block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- DAT block field-offset symbols: of the form 
0$f Id 

- XAB code and mask symbols: of the form 
XB$xxx 

- KEY block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- KEY block field-offset symbols: of the form 
0$f Id 

- XAB code and mask symbols: of the form 
XB$xxx 

- PRO block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- PRO block field-offset symbols: of the form 
0$f Id 

- XAB code and mask symbols: of the form 
XB$xxx 

- SUM block field-initialization macros: of 
the form X$fld 

- XAB end-block-declaration macro: XAB$E 

- SUM block field-offset symbols: of the form 
0$f Id 

- XAB code and mask symbols: of the form 
XB$xxx 



(Continued on next page) 
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MACROS THAT DECLARE SYMBOLS AND OTHER MACROS 

Table C-l (Cont.)'* Macros That Declare Symbols and Other Macros 



Macro Argument Declares 



XAB$BT 


DFIN$G 


- Global XAB code and mask symbols: 
form XB$xxx (except XAB length 
XB$LAL, XB$DTL , XB$KYL , XB$PRL, and 


of the 
symbol s : 
XB$SML) 


XAB$BT 


DF I N$L 


- Local XAB code and mask symbols: of 
XB$xxx (except XAB length symbols 
XB$DTL , XB$KYL, XB$PRL, and XB$SML) 


the form 
: XB$LAL , 


XABOF$ 




- XAB field offset symbols: of the form 0$fld 

- XAB length symbols: XB$LAL , XB$DTL, XB$KYL , 
XB$PRL , and XB$SML 


XAB0F$ 


DEF$SZ 


- XAB length symbols: XB$LAL, XB$DTL , 
XB$PRL, and XB$SML 


XB$KYL , 


XBAOF$ 




- ALL block 
0$f Id 

- ALL block 


field offset symbols: of 
length symbol: XB$LAL 


the form 


XBAOF$ 


DEF$SZ 


- ALL block 


length symbol: XB$LAL 




XBDOF$ 




- DAT block 
0$f Id 

- DAT block 


field offset symbols: of 
length symbol: XB$DTL 


the form 


XBDOF$ 


DEF$SZ 


- DAT block 


length symbol: XB$DTL 




XBKOF$ 




- KEY block 
0$f Id 

- KEY block 


field offset symbols: of 
length symbol: XB$KYL 


the form 


XBKOF$ 


DEF$SZ 


- KEY block 


length symbol: XB$KYL 




XBPOF$ 




- PRO block 
0$f Id 

- PRO block 


field offset symbols: of 
length symbol: XB$PRL 


the form 


XBPOF$ 


DEF$SZ 


- PRO block 


length symbol: XB$PRL 




XBSOF$ 




- SUM block 
0$f Id 

- SUM block 


field offset symbols: of 
length symbol: XB$SML 


the form 


XBSOF$ 


DEF$SZ 


- SUM block 


length symbol: XB$SML 





C-4 



APPENDIX D 
RMS-11 WITH DIFFERENT OPERATING SYSTEMS 

This appendix contrasts the behaviors of RMS-11 on different operating 
systems : 

• PRO/RMS-11 versus RSTS/E RMS-11 

• PRO/RMS-11 versus RSX-11M/M-PLUS RMS-11 

• RSTS/E RMS-11 versus RSX-11M/MPLUS RMS-11 

D.l PRO/RMS-11 VERSOS RSTS/E RMS-11 

This section contrasts the behaviors of PRO/RMS-11 and RSTS/E RMS-11. 
D.l.l Different Behaviors 

The following features behave differently for RSTS/E and P/OS users: 

• Macro library location 

RMS-11 macro libraries for the systems are located in the 
f i les : 

RSTS/E LB : RMSMAC .MLB 

P/OS LB : [1,1] RMSMAC . MLB 

• RTV field in FAB 

The RTV field in the FAB has different uses: 

RSTS/E Cluster size 

P/OS Retrieval pointer count 

• Maximum bucket size 

The maximum bucket sizes (given by the BKS field in the FAB or 
the BKZ fields in ALL blocks) are different: 

RSTS/E 15 blocks 

P/OS 32 blocks 
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RMS-11 WITH DIFFERENT OPERATING SYSTEMS 



Area alignment 



The meanings of area alignment codes (in the ALN field of an 
ALL block) are different: 



RSTS/E 



XB$LBN 



Cluster alignment 



P/OS 



XB$CYL 
XB$LBN 
XB$VBN 



Cylinder alignment 
Logical block alignment 
Virtual block alignment 



• Protection codes 

The protection codes (and defaults) are system-specific. 

D.1.2 Features Not Supported on RSTS/E 

The following RMS-11 features are not supported on RSTS/E, but are 
supported on P/OS: 

• ENTER operation ( $ ENTER macro) 

• NXTVOL operation ($NXTVOL macro) 

• REMOVE operation ($REMOVE macro) 

• SPACE operation ($SPACE macro) 

• WAIT operation ($WAIT macro) 

• User-provided interlocking (FB$UPI mask in SHR field of FAB) 

• File version numbers (NB$VER mask in FNB field of NAM) 

• Asynchronous execution of operations (RB$ASY mask in ROP field 
of RAB; SYN and AS YN arguments to RAB$B macro; RB$BLL symbol 
for length of asynchronous RAB) 

• Directories (DID field in NAM block) 

• Area extension (ALL block fields for $EXTEND macro) 

• Contiguous file extension (FB$CTG mask in FOP field of FAB for 
$ EXTEND macro) 

• Hard placement (XB$HRD mask in AOP field of ALL block) 

• Return of date and protection information by DISPLAY operation 
(PRO block fields and DAT block fields for $DISPLAY macro) 

• File expiration date ( EDT field of NAM block) and file 
revision number (RVN field of NAM block) 

D.1.3 Features Not Supported on P/OS 

On RSTS/E, for compatibility with older file system, RMS-11 treats 
certain sequential files with undefined records as sequential files 
with stream records. P/OS will allow only block access to such files. 
In addition, magtape devices are not supported on P/OS, and remote 
operations are not supported on P/OS. 
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RMS-11 WITH DIFFERENT OPERATING SYSTEMS 



D.2 PRO/RMS-11 VERSUS RSX-11M/M-PLUS RMS-11 

The P/OS operating system does not support magtape devices or remote 
RMS-11 operations. 

P/OS files have decimal version numbers (NB$VER mask in FNB field of 
NAM) . 



D.3 RSTS/E RMS-11 VERSOS RSX-11M/M-PLUS RMS-11 

This section contrasts the behaviors of RSTS/E RMS-11 and 
RSX-11M/M-PLUS RMS-11. 



D.3.1 Different Behaviors 

The following features behave differently for RSTS/E and 
RSX-11M/M-PLUS users: 

• Macro library location 

RMS-11 macro libraries for the systems are located in the 
f i les : 

RSTS/E LB : RMSMAC . MLB 

RSX-11M/M-PLUS LB: [ 1 , 1 ] RMSMAC .MLB 

• RTV field in FAB 

The RTV field in the FAB has different uses: 

RSTS/E Cluster size 

RSX-11M/M-PLUS Retrieval pointer count 

• Maximum bucket size 

The maximum bucket sizes (given by the BKS field in the FAB or 
the BKZ fields in ALL blocks) are different: 

RSTS/E 15 blocks 

RSX-11M/M-PLUS 32 blocks 

• Area alignment 

The meanings of area alignment codes (in the ALN field of an 
ALL block) are different: 

RSTS/E XB$LBN Cluster alignment 

RSX-11M/M-PLUS XB$CYL Cylinder alignment 

XB$LBN Logical block alignment 
XB$VBN Virtual block alignment 
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D.3.2 Features Not Supported on RSTS/E 

The following RMS-11 features are not supported on RSTS/E, but are 
supported on RSX-11M/M-PLUS : 

• ENTER operation ($ENTER macro) 

• NXTVOL operation ($NXTVOL macro) 

• REMOVE operation ($ REMOVE macro) 

• REWIND operation for magtape device ($REWIND macro) 

• SPACE operation ($SPACE macro) 

• WAIT operation ($WAIT macro) 

• User-provided interlocking (FB$UPI mask in SHR field of FAB) 

• Octal file version numbers (NB$VER mask in FNB field of NAM) 

• Asynchronous execution of operations (RB$ASY mask in ROP field 
of RAB; SYN and ASYN arguments to RAB$B macro; RB$BLL symbol 
for length of asynchronous RAB) 

• Directories (DID field in NAM block) 

• Area extension (ALL block fields for $EXTEND macro) 

• Contiguous file extension (FB$CTG mask in FOP field of FAB for 
$EXTEND macro) 

• Hard placement (XB$HRD mask in AOP field of ALL block) 

• Return of date and protection information by DISPLAY operation 
(PRO block fields and DAT block fields for $DISPLAY macro) 

• File expiration date (EDT field in NAM block) and file 
revision number (RVN field of NAM block) 

• Initial end-of-file context for magtape file (FB$NEF mask in 
FOP field of FAB for $OPEN macro) 

• Multivolume magtapes 
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$CLOSE macro, 5-3 
$COMPARE macro, 2-17 

example, 7-3, 7-7, 7-11, 7-15 
$CONNECT macro, 5-6 
$CREATE macro, 5-9 
$DELETE macro, 5-25 
$DISCONNECT macro, 5-27 
$DISPLAY macro, 5-29 

RSTS/E, D-4 
$ENTER macro, 5-35 

RSTS/E, D-4 
$ ERASE macro, 5-40 

example, 7-11 
$EXTEND macro, 5-46 

RSTS/E, D-4 
$FBCAL macro, C-2 
$FETCH macro, 2-16 

example, 7-3, 7-7, 7-11, 7-15 
$FIND macro 

key access, 5-51 

RFA access, 5-54 

sequential access, 5-49 
$FLUSH macro, 5-56 
$FREE macro, 5-58 
$GET macro 

key access, 5-63 

RFA access, 5-67 

sequential access, 5-60 
$GETGSA macro, 2-21 
$GNCAL macro , C-2 
$INIT macro (obsolete) , xiv 
$INITIF macro (obsolete) , xiv 
$NXTVOL macro, 5-70 

RSTS/E, D-4 
$OFF macro, 2-12 
$OPEN macro, 5-72 

RSTS/E, D-4 
$PARSE macro, 5-86 

example, 7-3, 7-7, 7-11, 7-15 
$PUT macro 

key access, 5-95 

sequential access, 5-91 
$RBCAL macro, C-3 
$READ macro 

sequential access, 5-98 

VBN access, 5-100 
$REMOVE macro, 5-102 

RSTS/E, D-4 
$RENAME macro, 5-108 

example, 7-15 
$RETURN macro, 2-20 
$REWIND macro, 5-114 

RSTS/E magtape device, D-4 
$RLCB system routine, 2-22 
$RMSTAT macro, C-3 
$RQCB system routine, 2-22 
$SEARCH macro, 5-116 

example, 7-7, 7-15 
$SET macro, 2-12 
$SETGSA macro, 2-20 
$SPACE macro, 5-120 



RSTS/E, D-4 
$STORE macro, 2-11 

example, 7-3, 7-7, 7-11, 7- 
$TESTB ITS macro, 2-18 
$TRUNCATE macro, 5-122 
$UPDATE macro, 5-124 
$WAIT macro, 5-126 

RSTS/E, D-4 
$WRITE macro 

sequential access, 5-127 

VBN access, 5-129 
.EVEN assembler directive 

control block alignment, 2- 

pool alignment, 2-4 
.MCALL assembler directive, 2 
/ML assembler switch, 2-22 

Access 

requested 

See FAC field in FAB 
shared 

See SHR field in FAB 
Access mode 
block 

See BKT field in RAB 
record 

See RAC field in RAB 

AID field in ALL block, 2-13 
CLOSE operation, 5-3 
CREATE operation, 5-9, 5-16 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 to 5 
offset, 6-2 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-3 

Al ignment 

See ALN field in ALL block 

ALL block 

chaining to FAB, 2-13 
declaring, 2-8 
initializing, 2-10 
summary, 6-2 

Allocation 

See ALQ field in ALL block 

See ALQ field in FAB 

XAB 

See ALL block 
ALN field in ALL block 
CREATE operation, 5-17 
DISPLAY operation, 5-30 
EXTEND operation, 5-47 
offset, 6-2 
OPEN operation, 5-79 
RSTS/E, D-4 
summary, 6-4 
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ALQ field in ALL block 

CREATE operation, 5-16, 5-21 

DISPLAY operation, 5-30 

EXTEND operation, 5-47 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-5 
ALQ field in FAB 

CREATE operation, 5-16, 5-21 

EXTEND operation, 5-46 to 5-47 

offset, 6-22 

OPEN operation, 5-78 

summary, 6-25 
ALQO field in ALL block 

offset, 6-2 
ALQ1 field in ALL block 

offset, 6-2 
ANSI magtape device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-118 
AOP field in ALL block 

CREATE operation, 5-17 to 5-18 

DISPLAY operation, 5-30 

EXTEND operation, 5-47 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-4 

summary 

XB$CTG mask, 6-6 
XB$HRD mask, 6-7 

Area 

al ignment 

See ALN field in ALL block 
allocation 

See ALQ field in ALL block 
bucket size 

See BKZ field in ALL block 
contiguity 

See XB$CTG mask in AOP field 
count 

See NOA field in SUM block 
default extension size 

See DEQ field in ALL block 
description, obtaining 

See DISPLAY operation 
extending allocation 

See EXTEND operation 
identi f ier 

See AID field in ALL block 
location 

See LOC field in ALL block 
See ALL block 
Assembly, 2-22 

ASYN argument to RAB$B macro, 
2-8 

RSTS/E, D-4 
Asynchronous operation 
RAB declaration, 2-8 
See RB$ASY mask in ROP field 
waiting for 

See WAIT operation 

BDB pool, 2-8 
BID field in FAB 



offset, 6-22 

summary 

FB$B ID code, 6-26 
BID field in RAB 

offset, 6-115 

summary 

RB$B ID code, 6-116 
Binary key 

See XB$BN2 mask in DTP field 

See XB$BN4 mask in DTP field 
BKS field in FAB 

CREATE operation, 5-17 

offset, 6-24 

OPEN operation, 5-78 

RSTS/E, D-3 

summary, 6-27 
BKT field in RAB, 4-6, 

4-12 to 4-13 

FIND operation, 5-50, 5-52, 
5-55 

GET operation, 5-61, 5-65, 

5-68 
offset, 6-115 
PUT operation, 5-93, 5-96 
READ operation, 5-98, 5-100 
SPACE operation, 5-120 
summary, 6-117 

WRITE operation, 5-127, 5-129 
BKZ field in ALL block 
CREATE operation, 5-17 
DISPLAY operation, 5-30 
offset, 6-2 
OPEN operation, 5-79 
RSTS/E, D-3 to D-4 
summary, 6-8 
BLN field in ALL block 
offset, 6-2 
summary 

XB$LAL code, 6-9 
BLN field in DAT block 
offset, 6-14 
summary 

XB$DTL code, 6-15 
BLN field in FAB 
offset, 6-22 
summary 

FB$BLN code, 6-28 
BLN field in KEY block 
offset, 6-67 
summary 

XB$KYL code, 6-69 
BLN field in PRO block 
offset, 6-108 
summary 

XB$PRL code, 6-109 
BLN field in RAB 
offset, 6-115 
summary, 6-118 
BLN field in SUM block 
offset, 6-145 
summary 

XB$SML code, 6-146 
Block 

access mode 

See BKT field in RAB 
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locating 

See SPACE operation 

reading 

See READ operation 

size, magtape 

See BLS field in FAB 

writing 

See WRITE operation 
Block context, 4-12 
Block operation, 4-14 
Block operation macro 

$READ, 5-98, 5-100 

$SPACE, 5-120 

$WRITE, 5-127, 5-129 

declaring, C-3 
Block processing, 4-11 
Block stream, 4-11 
Block-declaration macro, 2-8, 

2-10 
Blocked record 

See FB$BLK mask in RAT field 
BLS field in FAB 

CREATE operation, 5-15 

offset, 6-24 

OPEN operation, 5-79 

summary, 6-29 
BPA field in FAB, 2-7, 3-5 

CLOSE operation, 5-4 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-30 
BPS field in FAB, 2-7, 3-5 

CLOSE operation, 5-4 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-31 
Bucket 

fill number 
data 

See DFL field in KEY block 
honor ing 

See RB$LOA mask in ROP field 
index 

See IFL field in KEY block 

size 

See BKS field in FAB 
See BKZ field in ALL block 
Buffer 

record 

See RBF field in RAB 

user 



See UBF field in RAB 
Buffer pool, 3-5 

Call 

operation routine, 2-14 
arguments in memory, 2-15 
macro argument, 2-14 
Carriage control 

See RAT field in FAB 
Carriage-control device 

See FB$CCL mask in DEV field 
Carriage-return carriage control 

See FB$CR mask in RAT field 
Casette tape device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-118 
CDT field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-16 
Central buffer pool, 3-5 
Changed key 

See XB$CHG mask in FLG field 
CLOSE operation, 3-9 

$CLOSE macro, 5-3 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

wildcard loop, 3-11 
Cluster size 

See RTV field in FAB 
COD field in ALL block 

offset, 6-2 

summary 

XB$ALL code, 6-10 
COD field in DAT block 

offset, 6-14 

summary 

XB$DAT code, 6-17 
COD field in KEY block 

offset, 6-67 

summary 

XB$KEY code, 6-70 
COD field in PRO block 

offset, 6-108 

summary 

XB$PRO code, 6-110 
COD field in SUM block 

offset, 6-145 

summary 

XB$SUM code, 6-147 
Code and mask symbol 

declar ing 



ALL 


block , 


C- 


3 


to 


C- 


4 


DAT 


block , 


C- 


3 


to 


C- 


4 


FAB, 


C-1 












KEY 


block , 


C- 


3 


to 


C- 


4 


NAM 


block , 


C- 


2 








PRO 


block , 


C- 


3 


to 


C- 


4 


RAB, 


C-2 












SUM 


block , 


C- 


3 


to 


C- 


4 



XAB, C-4 

value 



ALL block, 6-2 
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DAT block, 6-14 
FAB , 6-22 
KEY block, 6-67 
NAM block, 6-94 
PRO block, 6-108 
RAB, 6-115 
SUM block, 6-145 
Code symbol 

See Code and mask symbol 
Completion 

handler, 2-18 

return macro 
declaring, C-2 

symbol 

declaring, C-3 
Completion status 

See STS field in FAB 

See STS field in RAB 

See STV field in FAB 

See STV field in RAB 
CONNECT operation 

$CONNECT macro, 5-6 

BDB requirement, 2-8 

block stream, 4-13 

I/O buffer requirement, 2-7 

IRAB requirement, 2-5 

key buffer requirement, 2-6 

record stream, 4-8 
Context 

block stream, 4-12 

record stream, 4-3 
Cont igui ty 

See FB$CTG mask in FOP field 

See XB$CTG mask in AOP field 
Control block, 1-2 

chaining, 2-13 

declaring, 2-8 

examining, 2-16 

field 

See Field 

initializing, 2-8 

setting up, 2-11 
CRE argument to ORG$ macro, 2-3 
CREATE operation, 3-8 

$CREATE macro, 5-9 

BDB requirement, 2-8 

declaring with ORG$ macro, 2-3 

I/O buffer requirement, 2-7 

I FAB requirement, 2-5 

wildcard loop, 3-11 
Creation date 

See CDT field in DAT block 
CTX field in FAB, 2-20 

offset, 6-22 

summary, 6-32 
CTX field in RAB, 2-20 

offset, 6-115 

summary, 6-119 
Current-record context, 4-3 

DAN field in KEY block 
CREATE operation, 5-19 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 



summary, 6-71 
DAT block 

chaining to FAB, 2-13 to 2-14 

declaring, 2-8 

initializing, 2-10 

summary, 6-14 
Data area number 

See DAN field in KEY block 
Date 

See DAT block 

XAB 

See DAT block 
DBS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-72 
DECtape device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 
DECTAPE II device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 
DEF$SZ argument, C-l 
Default extension size 

See DEQ field in ALL block 

See DEQ field in FAB 
Default string 

See DNA field in FAB 
Deferred writing 

See FB$DFW mask in FOP field 
DEL argument to ORG$ macro, 2-3 
DELETE operation, 4-11 

$DELETE macro, 5-25 

declaring with 0RG$ macro, 2-3 
Deletion, file marked for 

See FB$MKD mask in FOP field 
DEQ field in ALL block 

CREATE operation, 5-17 

DISPLAY operation, 5-30 

offset, 6-2 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-11 
DEQ field in FAB 

CREATE operation, 5-17 

offset, 6-22 

OPEN operation, 5-74, 5-78 
summary, 6-33 
DEV field in FAB, 3-1 to 3-2 
CREATE operation, 5-20 
ENTER operation, 5-37 
ERASE operation, 5-42 to 5-43 
offset, 6-24 
OPEN operation, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-104 
RENAME operation, 5-111 
SEARCH operation, 

5-117 to 5-118 
summary, 6-34 
Dev ice 

characteristics 

See DEV field in FAB 
identifier 



Index-4 



INDEX 



See DVI field in NAM block 

DFIN$G argument, C-l 

DFIN$L argument, C-l 

DFL field in KEY block 
CREATE operation, 5-20 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-73 

DID field in NAM block 

CREATE operation, 5-10, 5-21 
ENTER operation, 5-36 to 5-37 
ERASE operation, 5-41 to 5-42 
offset, 6-94 

OPEN operation, 5-73, 5-77 

PARSE operation, 5-87 

REMOVE operation, 5-103, 5-105 

RENAME operation, 
5-109 to 5-111 

SEARCH operation, 5-116, 5-118 

summary, 6-95 
DID field in NAM block field 

RSTS/E, D-4 
Di rectory 

wildcard context 

See WD I field in NAM block 

wildcard operation 

See NB$WCH mask in FNB field 
Directory entry 

creating 

See ENTER operation 

deleting 

See REMOVE operation 

replacing 

See RENAME operation 
Directory operation, 3-5 
Directory operation macro 

$ENTER, 5-35 

$PARSE, 5-86 

$ REMOVE, 5-102 

$RENAME, 5-108 

$SEARCH, 5-116 

declaring, C-2 
Directory processing, 3-1 
DISCONNECT operation 

$DISCONNECT macro, 5-27 

block stream, 4-14 

record stream, 4-9 
Disk device, 3-1, 5-20, 5-37, 

5-42, 5-77, 5-88, 5-104, 

5-111, 5-117 
DISPLAY operation, 3-8 

$DISPLAY macro, 5-29 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

wildcard loop, 3-11 
DNA field in FAB, 3-3 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 

offset, 6-24 

OPEN operation, 5-73 

PARSE operation, 5-87 

REMOVE operation, 5-103 

RENAME operation, 



5-109 to 5-110 

summary, 6-35 
DNS field in FAB, 3-3 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 

offset, 6-24 

OPEN operation, 5-73 

PARSE operation, 5-87 

REMOVE operation, 5-103 

RENAME operation, 
5-109 to 5-110 

summary, 6-36 
DTP field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-74 
Duplicate key 

See XB$DUP mask in FLG field 
DVB field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-75 
DVI field in NAM block, 3-3 

CREATE operation, 5-10, 5-21 

ENTER operation, 5-36 to 5-37 

ERASE operation, 5-41 to 5-42 

offset, 6-94 

OPEN operation, 5-73, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-103, 5-105 
RENAME operation, 

5-109 to 5-111 
SEARCH operation, 5-116 
summary, 6-96 

EDT field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

summary, 6-18 
EDT field in NAM block 

RSX-11, D-4 
ENTER operation, 3-6 

$ENTER macro, 5-35 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

I FAB requirement, 2-5 

wildcard loop, 3-11 
ER$-family symbol 

declaring, C-3 

value, A-l to A-19 
ERASE operation, 3-8 

$ERASE macro, 5-40 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
Error 

assembly-time, 2-22 
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fatal, 2-16 
handler, 2-18 
ESA field in NAM block, 3-3, 
3-10 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-116 

summary, 6-97 
ESL field in NAM block 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

SEARCH operation, 5-116 

summary, 6-98 
ESS field in NAM block 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-94 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

summary, 6-99 
Expanded string 

See ESA field in NAM block 
EXTEND operation, 3-9 

$EXTEND macro, 5-46 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

wildcard loop, 3-11 
Extended attribute block 

See XAB 

F$-family macro, 2-10 
declaring, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FAB 

chaining to RAB, 2-14 

declaring, 2-8 

initializing, 2-10 

summary, 6-22 
FAB field in RAB, 4-2 

chaining FAB to RAB, 2-14 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-120 
FAB$B macro, 2-8, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FAB$BT macro, C-l 
FAB$E macro, 2-10 

declaring, C-l 

example, 7-3, 7-7, 7-11, 7-15 
FABOF$ macro, C-l 



FAC field in FAB 

CREATE operation, 5-14 

offset, 6-22 

OPEN operation, 5-75 

summary, 6-37 
Facilities-declaration macro, 

2- 2 

declaring, C-2 
Fast deletion 

See RB$FDL mask in ROP field 
Fatal error, 2-16 
FB$-family symbol 

declaring, C-l 
FB$B ID code in BID field 

summary, 6-26 

value, 6-22 
FB$BLK mask in RAT field 

CREATE operation, 5-11 

OPEN operation, 5-78 

summary, 6-60 

value, 6-23 
FB$BLN code in BLN field 

summary, 6-28 

value, 6-22 
FB$CCL mask in DEV field, 3-1 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-117 

value, 6-24 
FB$CR mask in RAT field 

CREATE operation, 5-12 

OPEN operation, 5-78 

value, 6-23 
FB$CTG mask in FOP field 

CREATE operation, 5-18 

EXTEND operation, 5-46 

OPEN operation, 5-78 

RSTS/E, D-4 

summary, 6-40 

value, 6-23 
FB$DEL mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$DFW mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 

summary, 6-41 

value, 6-23 
FB$DLK mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 

summary, 6-42 

value, 6-23 
FB$FID mask in FOP field, 3-8, 

3- 10 to 3-12 

CREATE operation, 5-10 
ENTER operation, 5-36 
ERASE operation, 5-41 
OPEN operation, 5-73 to 5-74 



Index-6 



INDEX 



REMOVE operation, 5-103 

RENAME operation, 
5-109 to 5-110 

summary, 6-43 

value, 6-23 
FB$FIX code in RFM field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$FTN mask in RAT field 

CREATE operation, 5-12 

OPEN operation, 5-78 

value, 6-23 
FB$GET mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$GET mask in SHR field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$IDX code in ORG field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-2 3 
FB$MDI mask in DEV field, 3-1 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-117 

value, 6-24 
FB$MKD mask in FOP field 

CREATE operation, 5-11 

summary, 6-44 

value, 6-23 
FB$NEF mask in FOP field 

OPEN operation, 5-76 

RSTS/E, D-4 

summary, 6-45 

value, 6-23 
FB$NIL mask in SHR field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$POS mask in FOP field 

CREATE operation, 5-15 

summary, 6-46 

value, 6-23 
FB$PRN mask in RAT field 

CREATE operation, 5-12 

OPEN operation, 5-78 

value, 6-23 
FB$PUT mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$REA mask in FAC field 

CREATE operation, 5-14 

OPEN operation, 5-75 

value, 6-22 
FB$REC mask in DEV field, 



3-1 to 3-2 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-42 to 5-43 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 
5-117 to 5-118 

value, 6-24 
FB$REL code in ORG field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$RWC mask in FOP field 

CLOSE operation, 5-4 

CREATE operation, 5-15 

OPEN operation, 5-77 

SEARCH operation, 5-117 

summary, 6-47 

value, 6-23 
FB$RWO mask in FOP field 

CREATE operation, 5-15 

OPEN operation, 5-76 

SEARCH operation, 5-117 

summary, 6-48 

value, 6-23 
FB$SDI mask in DEV field, 3-2 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-118 

value, 6-24 
FB$SEQ code in ORG field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$SQD mask in DEV field, 3-2 

CREATE operation, 5-20 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-77 

PARSE operation, 5-88 

REMOVE operation, 5-104 

RENAME operation, 5-111 

SEARCH operation, 5-118 

value, 6-24 
FB$STM code in RFM field 

CREATE operation, 5-11 

OPEN operation, 5-78 

value, 6-23 
FB$SUP mask in FOP field 

CREATE operation, 5-10 

summary, 6-49 

value, 6-23 
FB$TMD mask in FOP field 

CREATE operation, 5-11 

value, 6-23 
FB$TMP mask in FOP field 

CREATE operation, 5-11 
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summary, 6-50 
value, 6-23 
FB$TRM mask in DEV field, 3-1 
CREATE operation, 5-20 
ENTER operation, 5-37 
ERASE operation, 5-42 
OPEN operation, 5-77 
PARSE operation, 5-88 
REMOVE operation, 5-104 
RENAME operation, 5-111 
SEARCH operation, 5-117 
value, 6-24 



setting up, 2-11 

testing bits in, 2-18 
Field-access macro 

$COMPARE, 2-17 

$FETCH, 2-16 

$OFF, 2-12 

$SET, 2-12 

$STORE, 2-11 

$TESTBITS, 2-18 

declaring, C-2 
Field-initialization macro, 2-10 

declaring 



FB$TRN mask in FAC 


field 


ALL block, 


C-3 








CREATE operation, 


5-14 


DAT block, 


C-3 








OPEN operation, 5 


-75 


FAB, C-l 










value, 6-22 




KEY block, 


C-3 








FB$UDF code in RFM 


field 


NAM block, 


C-2 








CREATE operation, 


5-11 


PRO block, 


C-3 








OPEN operation, 5 


-78 


RAB, C-2 










value, 6-23 




SUM block, 


C-3 








FB$UPD mask in FAC 


field 


Field-offset s 


ymbol 








CREATE operation, 


5-14 


declaring 










OPEN operation, 5 


-75 


ALL block, 


C-3 


to 


C- 


4 


value, 6-22 




DAT block, 


C-3 


to 


C- 


4 


FB$UPI mask in SHR 


field 


FAB, C-l 










CREATE operation, 


5-14 


KEY block, 


C-3 


to 


C- 


4 


OPEN operation, 5 


-75 


NAM block, 


C-2 








value, 6-22 




PRO block, 


C-3 


to 


C- 


4 


FB$UPI mask in SHR 


field of FAB 


RAB, C-2 










RSX-11, D-4 




SUM block, 


C-3 


to 


C- 


4 


FB$VAR code in RFM 


field 


XAB, C-4 










CREATE operation, 


5-11 


value 










OPEN operation, 5 


-78 


ALL block, 


6-2 








value, 6-23 




DAT block, 


6-14 








FB$VFC code in RFM 


field 


FAB, 6-22 










CREATE operation, 


5-11 


KEY block, 


6-67 








OPEN operation, 5 


-78 


NAM block, 


6-94 








value, 6-23 




PRO block, 


6-108 






FB$WRI mask in SHR 


field 


RAB, 6-115 










CREATE operation, 


5-14 


SUM block, 


6-145 






OPEN operation, 5 


-75 


File 










value, 6-22 




access requested 








FB$WRT mask in FAC 


field 


See FAC field in 


FAB 




CREATE operation, 


5-14 


access shared 









OPEN operation, 5-75 
value, 6-22 
FID field in NAM block 
CREATE operation, 5-21 
ENTER operation, 5-36 
ERASE operation, 5-41 to 5-42 
offset, 6-94 

OPEN operation, 5-73, 5-77 
REMOVE operation, 5-105 
RENAME operation, 5-111 
SEARCH operation, 5-118 
summary, 6-100 
Field, 1-2 

clearing bits in, 2-12 
comparing value, 2-17 
copying value from, 2-16 
copying value into, 2-11 
examining, 2-16 
initializing, 2-8 
mnemonic, 1-2 
setting bits in, 2-12 



See SHR field in FAB 
al ignment 

See ALN field in ALL block 
allocation 

See ALQ field in ALL block 

See ALQ field in FAB 
area 

See ALL block 
bucket size 

See BKS field in FAB 

See BKZ field in ALL block 
clos ing 

See CLOSE operation 
cluster size 

See RTV field in FAB 
contiguity 

See FB$CTG mask in FOP field 

See XB$CTG mask in AOP field 
creating 

See CREATE operation 
creation date 
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See CDT field in DAT block 
date 

See DAT block 
default extension size 

See DEQ field in ALL block 

See DEQ field in FAB 
deleti ng 

See ERASE operation 
extending allocation 

See EXTEND operation 
identifier 

See FID field in NAM block 
internal file identifier 

See IFI field in FAB 
location 

See LOC field in ALL block 
locking 

See FB$DLK mask in FOP field 
name block 

See NAM block 
opening 

See OPEN operation 
organi zat ion 

See ORG field in FAB 
owner 

See PRG field in PRO block 
protection 

See PRO field in PRO block 
record-output characteristic 

See RAT field in FAB 
renaming 

See RENAME operation 
revision date 

See RDT field in DAT block 
revision number 

See RVN field in DAT block 
specification string 

default 

See DNA field in FAB 

parsing 

See FNB field in NAM block 

See FNA field in FAB 
str ing 

See FNA field in FAB 
supersession 

See FB$SUP mask in FOP field 
truncating 

See TRUNCATE operation 
wildcard context 

See WCC field in NAM block 
wildcard operation 

See NB$WCH mask in FNB field 
wildcard search 

See SEARCH operation 
File access block 

See FAB 
File operation, 3-7 
File operation macro 
$CLOSE, 5-3 
$CREATE, 5-9 
$DISPLAY, 5-29 
$ERASE , 5-40 
$EXTEND, 5-46 
$OPEM / 5-72 
declaring, C-2 



File processing, 3-1 
File specification 

fully qualified, 3-4 

merged string, 3-3 

parsing 

See PARSE operation 

wildcard, 3-9 
Fill number 

data bucket 

See DFL field in KEY block 

index bucket 

See IFL field in KEY block 
FIN argument to ORG$ macro, 2-3 
FIND operation, 4-10 

$FIND macro 

key access, 5-51 
RFA access, 5-54 
sequential access, 5-49 

declaring with ORG$ macro, 2-3 
Fixed-control -si ze 

See FSZ field in FAB 
Fixed-length record format 

See FB$FIX code in RFM field 
FLG field in KEY block 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary 

XB$CHG mask, 6-76 
XB$DUP mask, 6-77 
XB$NUL mask, 6-78 
FLUSH operation 

$FLUSH macro, 5-56 

record stream, 4-8 
FNA field in FAB, 3-3 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 

offset, 6-24 

OPEN operation, 5-73 

PARSE operation, 5-87 

REMOVE operation, 5-103 

RENAME operation, 
5-109 to 5-110 

summary, 6-38 
FNB field in NAM block, 3-3, 

3-10 to 3-11 

CREATE operation, 5-21 

ENTER operation, 5-37 to 5-38 

ERASE operation, 5-41, 5-43 

offset, 6-94 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-103, 5-105 

RENAME operation, 5-109, 
5-111 to 5-112 

SEARCH operation, 5-116, 5-118 

summary, 6-101 

NB$WCH mask, 6-102 

wildcard loop, 3-11 
FNS field in FAB, 3-3 

CREATE operation, 5-10 

ENTER operation, 5-36 

ERASE operation, 5-41 
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offset, 6-24 
OPEN operation, 5-73 
PARSE operation, 5-87 
REMOVE operation, 5-103 
RENAME operation, 

5-109 to 5-110 
summary, 6-39 
FOP field in FAB, 3-8, 
3-10 to 3-12 
CLOSE operation, 5-4 
CREATE operation, 

5-10 to 5-11, 5-15, 5-18 
ENTER operation, 5-36 
ERASE operation, 5-41 
EXTEND operation, 5-46 
offset, 6-23 

OPEN operation, 5-73 to 5-74, 

5-76 to 5-78 
REMOVE operation, 5-103 
RENAME operation, 

5-109 to 5-110 
SEARCH operation, 5-117 
summary 

FB$CTG mask, 6-40 

FB$DFW mask, 6-41 

FB$DLK mask, 6-42 

FB$F ID mask, 6-43 

FB$MKD mask, 6-44 

FB$NEF mask, 6-45 

FB$POS mask, 6-46 

FB$RWC mask, 6-47 

FB$RWO mask, 6-48 

FB$SUP mask, 6-49 

FB$TMP mask, 6-50 
FORTRAN-s tyle carriage control 
See FB$FTN mask in RAT field 
FREE operation 

$FREE macro, 5-58 
block stream, 4-13 
record stream, 4-9 
Free-space list for pool, 2-21 
FSZ field in FAB 

CREATE operation, 5-11 
offset , 6-24 
OPEN operation, 5-78 
summary, 6-51 

GET argument to ORG$ macro, 2-3 
GET operation, 4-10 
$GET macro 

key access, 5-63 
RFA access, 5-67 
sequential access, 5-60 
declaring with ORG$ macro, 2-3 
Get-space routine, 2-20 
example, 7-18 
macro 

declaring, C-2 
RMS-ll-supplied , 2-4 
GSA$ macro, 2-20 

example, 7-3, 7-7, 7-11, 7-15 

Hard location 

See XB$HRD mask in AOP field 



I/O buffer pool, 2-6 
IAN field in KEY block 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-79 
IBS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN, operation, 5-80 

summary, 6-80 
IDB pool, 2-5 

IDX argument to ORG$ macro, 2-3 
I FAB pool, 2-5 
IFI field in FAB 

CLOSE operation, 5-3 to 5-4 

CONNECT operation, 5-6 

CREATE operation, 5-20 

DISPLAY operation, 5-30 

EXTEND operation, 5-46 

offset, 6-22 

OPEN operation, 5-77 

summary, 6-52 
IFL field in KEY block 

CREATE operation, 5-20 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-81 
Index 

area bucket size 

See IBS field in KEY block 

area number 
higher levels 

See IAN field in KEY block 
lowest level 

See LAN field in KEY block 

count 

See NOK field in SUM block 
data bucket size 

See DBS field in KEY block 
data bucket VBN 

See DVB field in KEY block 
description, obtaining 

See DISPLAY operation 
level count 

See LVL field in KEY block 
reference number 

See REF field in KEY block 
root bucket VBN 

See RVB field in KEY block 
See KEY block 
Indexed file 

declaring with ORG$ macro, 2-3 
Indexed file organization 

See FB$IDX code 
Initiali zation 

field, 2-10 
Integer key 

See XB$IN2 mask in DTP field 
See XB$IN4 mask in DTP field 
Internal file identifier 

See IFI field in FAB 
Internal stream identifier 
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See ISI field in RAB 

IRAB pool, 2-5 

ISI field in RAB, 4-2 
CONNECT operation, 5-7 
DELETE operation, 5-25 
DISCONNECT operation, 5-27 
FIND operation, 5-49, 5-51, 
5-54 

FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-60, 5-63, 
5-67 

NXTVOL operation, 5-70 

offset, 6-115 

PUT operation, 5-91, 5-95 

READ operation, 5-98, 5-100 

REWIND operation, 5-114 

SPACE operation, 5-120 

summary, 6-121 

TRUNCATE operation, 5-122 

UPDATE operation, 5-124 

WAIT operation, 5-126 

WRITE operation, 5-127, 5-129 

KBF field in RAB, 4-5 

FIND operation, 5-52 

GET operation, 5-63 

offset, 6-115 

PUT operation, 5-96 

summary, 6-122 
Key 

buffer address 

See KBF field in RAB 
buffer size 

See KSZ field in RAB 
changes 

See XB$CHG mask in FLG field 
characteristics 

See FLG field in KEY block 
data type 

See DTP field in KEY block 
duplication 

See XB$DUP mask in FLG field 
match criterion 

See RB$KGE mask in ROP field 

See RB$KGT mask in ROP field 
name 

See KNM field in KEY block 
null character 

See NUL field in KEY block 
reference 

See KRF field in RAB 
segment 

position 

See POS field in KEY block 

si ze 

See SIZ field in KEY block 
segment count 

See NSG field in KEY block 
size, total 

See TKS field in KEY block 
XAB 

See KEY block 
KEY block 

chaining to FAB, 2-13 to 2-14 



declaring, 2-8 

initializing, 2-10 

summary, 6-67 
Key buffer pool, 2-6 
Key record access 

See RB$KEY code in RAC field 
KNM field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-30 

offset, 6-68 

OPEN operation, 5-74 

summary, 6-82 
KRF field in RAB, 4-5 

CONNECT operation, 5-7 

FIND operation, 5-51 

GET operation, 5-63 

offset, 6-115 

REWIND operation, 5-114 

summary, 6-123 
KSZ field in RAB, 4-5 to 4-6 

FIND operation, 5-52 

GET operation, 5-63 

offset, 6-115 

PUT operation, 5-96 

summary, 6-124 

LAN field in KEY block 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

offset, 6-67 

OPEN operation, 5-80 

summary, 6-83 
LCH field in FAB, 3-2 

CREATE operation, 5-13 

ENTER operation, 5-36 

ERASE operation, 5-42 

offset, 6-24 

OPEN operation, 5-74 

PARSE operation, 5-87 

REMOVE operation, 5-104 

RENAME operation, 5-110 

SEARCH operation, 5-117 

summary, 6-53 
LOC field in ALL block 

CREATE operation, 5-17 

EXTEND operation, 5-47 

offset, 6-2 

RSTS/E, D-4 

summary, 6-12 
LOCO field in ALL block 

offset, 6-2 
LOCI field in ALL block 

offset, 6-2 
Locate mode 

See RB$LOC mask in ROP field 
Location 

hard 

See XB$HRD mask in AOP field 

See LOC field in ALL block 
Locking, file 

See FB$DLK mask in FOP field 
Logical channel number 

See LCH field in FAB 
LRL field in FAB 

CREATE operation, 5-20 
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offset, 6-24 
OPEN operation, 5-79 
summary, 6-54 
LVL field in KEY block 
DISPLAY operation, 5-32 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-84 

Macro library 

RMSMAC . MLB , 2-22 

RSTS/E, D-3 
Macro-declaration macro, 2-2 
Magtape 

pos i t i on i ng 

See FB$NEF mask in FOP field 
See FB$POS mask in FOP field 
See RB$EOF mask in ROP field 

rewind-after-closing 

See FB$RWC mask in FOP field 

rewind- be fore-creating 

See FB$RWO mask in FOP field 

rewi nd-bef ore-open i ng 

See FB$RWO mask in FOP field 
Magtape block size 

See BLS field in FAB 
Magtape device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-118 

ANSI, 3-2, 5-20, 5-37, 5-43, 
5-77, 5-88, 5-104, 5-111, 
5-118 

P/OS, D-3 
Mark-for-deletion 

See FB$MKD mask in FOP field 
Mask symbol 

See Code and mask symbol 
Mass insertion 

See RB$MAS mask in ROP field 
Match criterion 

See RB$KGE mask in ROP field 

See RB$KGT mask in ROP field 
MBC field in RAB 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-125 
MBF field in RAB 

CONNECT operation, 5-6 

offset, 6-115 

summary, 6-126 
Merged string, 3-3 
MRL field in KEY block 

DISPLAY operation, 5-32 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-85 
MRN field in FAB 

CREATE operation, 5-13 

offset, 6-24 

OPEN operation, 5-79 

summary, 6-55 
MRS field in FAB 

CREATE operation, 5-12 

offset, 6-24 

OPEN operation, 5-79 



summary, 6-56 
Multiblock count 

See MBC field in RAB 
Multibuffer count 

See MBF field in RAB 
Multidirectory device 

See FB$MDI mask in DEV field 

N$-family macro, 2-10 
declaring, C-2 

example, 7-3, 7-7, 7-11, 7-15 
NAM block 

chaining to FAB, 2-13 

declaring, 2-8 

identification by 

See FB$FID mask in FOP field 

initializing, 2-10 

summary, 6-94 
NAM field in FAB 

chaining NAM block to FAB, 
2-13 

CREATE operation, 5-9 

ENTER operation, 5-35 

ERASE operation, 5-40 

offset, 6-24 

OPEN operation, 5-72 

PARSE operation, 5-86 

REMOVE operation, 5-102 

RENAME operation, 5-108 

SEARCH operation, 5-116 

summary, 6-57 
NAM$B macro, 2-8, C-2 

example, 7-3, 7-7, 7-11, 7-15 
NAM$E macro, 2-10 

declaring, C-2 

example, 7-3, 7-7, 7-11, 7-15 
NAMOF$ macro, C-2 
NB$-family symbol 

declaring, C-2 
NB$DEV mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$DIR mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$NAM mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation 

(set if NB$QUO is set) , 5-88 

REMOVE operation, 5-105 
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RENAME operation, 5-111 

value, 6-94 
NB $NOD mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$QUO mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$TYP mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation 

(set if NB$QUO is set), 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$VER mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$VER mask in FNB field of NAM 

RSX-11, D-3 to D-4 
NB$WCH mask in FNB field, 

3-10 to 3-11 

CREATE operation, 5-21 

ENTER operation, 5-38 

ERASE operation, 5-41, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-103, 5-105 

RENAME operation, 5-109, 5-112 

SEARCH operation, 5-116, 5-118 

summary, 6-102 

value, 6-94 

wildcard loop, 3-11 
NB$WDI mask in FNB field 

CREATE operation, 5-21 

ENTER operation, 5-37 

ERASE operation, 5-43 

OPEN operation, 5-81 

PARSE operation, 5-88 

REMOVE operation, 5-105 

RENAME operation, 5-111 

value, 6-94 
NB$WNA mask in FNB field 

CREATE operation, 5-21 



ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

NB$WTY mask in FNB field 
CREATE operation, 5-21 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

NB$WVE mask in FNB field 
CREATE operation, 5-21 
ENTER operation, 5-37 
ERASE operation, 5-43 
OPEN operation, 5-81 
PARSE operation, 5-88 
REMOVE operation, 5-105 
RENAME operation, 5-111 
value, 6-94 

Next-record context, 4-3 

NOA field in SUM block 
DISPLAY operation, 5-32 
offset, 6-145 
OPEN operation, 5-81 
summary, 6-148 

NOK field in SUM block 
DISPLAY operation, 5-32 
offset, 6-145 
OPEN operation, 5-81 
summary, 6-149 

NSG field in KEY block 
DISPLAY operation, 5-31 
offset, 6-68 
OPEN operation, 5-81 
summary, 6-86 

NUL field in KEY block 
CREATE operation, 5-19 
DISPLAY operation, 5-31 
offset, 6-67 
OPEN operation, 5-80 
summary, 6-87 

Null key character 

See NUL field in KEY block 
See XB$NUL mask in FLG field 

NXT field in ALL block 
CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-2 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-13 

NXT field in DAT block 
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CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-14 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-19 

NXT field in KEY block 
CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-67 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-8 8 

NXT field in PRO block 
CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-108 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-111 

NXT field in SUM block 
CLOSE operation, 5-3 
CREATE operation, 5-9 
DISPLAY operation, 5-30 
ENTER operation, 5-35 
ERASE operation, 5-40 
EXTEND operation, 5-46 
offset, 6-145 
OPEN operation, 5-73 
PARSE operation, 5-86 
REMOVE operation, 5-102 
RENAME operation, 5-108 
SEARCH operation, 5-116 
summary, 6-150 

NXT field in XAB 

chaining XABs to FAB, 2-13 

NXTVOL operation 

$NXTVOL macro, 5-70 
record stream, 4-9 

0$-family symbol 
declar i ng 

ALL block, C-3 to C-4 
DAT block, C-3 to C-4 



FAB field offset, C-l 

KEY block, C-3 to C-4 

NAM block field offset, C-2 

PRO block, C-3 to C-4 

RAB, C-2 

SUM block, C-3 to C-4 
XAB, C-4 
value 

ALL block, 6-2 
DAT block, 6-14 
FAB, 6-22 to 6-24 
KEY block, 6-67 to 6-68 
NAM block, 6-94 
PRO block, 6-108 
RAB, 6-115 
SUM block, 6-145 
OPEN operation, 3-8 
$OPEN macro, 5-72 
BDB requirement, 2-8 
I/O buffer requirement, 2-7 
I FAB requirement, 2-5 
wildcard loop, 3-11 to 3-12 
Operation, 1-2 
routine 

calling, 2-14 
return, 2-15 
using, 2-10 
Operation macro, 1-2, 2-10 
ORG field in FAB 

CREATE operation, 5-11 
offset, 6-23 
OPEN operation, 5-78 
summary, 6-58 
ORG$ macro, 2-2 
Organization, file 

See ORG field in FAB 
Owner, file 

See PRG field in PRO block 

P$-family macro 

declaring, C-2 
P$BDB macro 

argument computation, 2-8 

format, 2-4 
P$BUF macro 

argument computation, 2-7 

format, 2-4 
P$FAB macro 

argument computation, 2-5 

format, 2-4 
P$IDX macro 

argument computation, 2-5 

format, 2-4 
P$RAB macro 

argument computation, 2-5 

format, 2-4 
P$RABX macro 

argument computation, 
2-5 to 2-6 

format, 2-4 
Packed decimal key 

See XB$PAC mask in DTP field 
PARSE operation, 3-6 

$PARSE macro, 5-86 

BDB requirement, 2-8 
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I/O buffer requirement, 2-7 
I FAB requirement, 2-5 
wildcard initialization, 3-10 
Pool 

buffer descriptor block, 2-8 

declaring space, 2-4 

free-space list, 2-21 

I/O buffer, 2-6 

index descriptor block, 2-5 

internal FAB, 2-5 

internal RAB, 2-5 

key buffer, 2-6 

See also Get-space routine 
POOL$B macro, 2-4, C-2 
POOL$E macro, 2-4 

declaring, C-2 
Pool-declaration macro, 2-4 

declaring, C-2 
POS field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-89 
POS0 field in KEY block 

offset, 6-68 
POS1 field in KEY block 

offset, 6-68 
POS2 field in KEY block 

offset, 6-68 
POS3 field in KEY block 

offset, 6-68 
POS4 field in KEY block 

offset, 6-68 
P0S5 field in KEY block 

offset, 6-68 
POS6 field in KEY block 

offset, 6-68 
POS7 field in KEY block 

offset, 6-68 
Positioning 

magtape 

See FB$NEF mask in FOP field 
See FB$POS mask in FOP field 
PRG field in PRO block 

CLOSE operation, 5-3 

DISPLAY operation, 5-32 

offset, 6-108 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-112 
Printer device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 
Private buffer pool 

See BPA field in FAB 

See BPS field in FAB 
PRJ field in PRO block 

CLOSE operation, 5-3 

DISPLAY operation, 5-32 

offset, 6-108 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-113 
PRO block 



chaining to FAB, 2-13 to 2-14 

declaring, 2-9 

initializing, 2-10 

summary, 6-108 
PRO field in PRO block 

CLOSE operation, 5-3 

CREATE operation, 5-11 

DISPLAY operation, 5-32 

offset, 6-108 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-114 
PRO/RMS-11 

contrasted with RSTS/E RMS-11, 
D-l 

contrasted with RSX-11 RMS-11, 
D-3 

Prologue version number 

See PVN field in SUM block 

Protection 
file 

See PRO field in PRO block 
XAB 

See PRO block 
PUT argument to ORG$ macro, 2-3 
PUT operation, 4-10 
$PUT macro 

key access, 5-95 
sequential access, 5-91 
declaring with ORG$ macro, 2-3 
PVN field in SUM block 
DISPLAY operation, 5-32 
offset, 6-145 
OPEN operation, 5-81 
summary, 6-151 

R$-family macro, 2-10 

declaring, C-2 
RAB 

declaring, 2-8 

initializing, 2-10 

summary, 6-115 
RAB$B macro, 2-8, C-2 
RAB$BT macro, C-2 
RAB$E macro, 2-10 

declaring, C-2 
RABOF$ macro, C-2 
RAC field in RAB, 4-4 to 4-6 

FIND operation, 5-49, 5-51, 
5-54 

GET operation, 5-60, 5-63, 
5-67 

offset, 6-115 

PUT operation, 5-91, 5-95 

summary, 6-127 
RAT field in FAB 

CREATE operation, 5-11 to 5-12 

offset, 6-23 

OPEN operation, 5-78 

summary, 6-59 

FB$BLK mask, 6-60 
RB$-family symbol 

declaring, C-2 
RB$ASY mask in ROP field, 4-1 

CONNECT operation, 5-7 
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DELETE operation, 5-25 
DISCONNECT operation, 5-27 
FIND operation, 5-49, 5-51, 
5-54 

FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-60, 5-63, 
5-67 

NXTVOL operation, 5-70 
PUT operation, 5-91, 5-95 
READ operation, 5-98, 5-100 
REWIND operation, 5-114 
RSTS/E, D-4 

SPACE operation, 5-120 
summary, 6-131 
TRUNCATE operation, 5-122 
UPDATE operation, 5-124 
value, 6-115 

WRITE operation, 5-127, 5-129 
RB$B ID code in BID field 

summary, 6-116 

value, 6-115 
RB$BLL code in BLN field 

RSTS/E, D-4 

value, 6-115 
RB$BLN code in BLN field 

value, 6-115 
RB$EOF mask in ROP field 

CONNECT operation, 5-7 

summary, 6-132 

value, 6-115 
RB$FDL mask in ROP field 

DELETE operation, 5-25 

summary, 6-133 

value, 6-115 
RB$KEY code in RAC field, 4-5 

FIND operation, 5-51 

GET operation, 5-63 

PUT operation, 5-95 

value, 6-115 
RB$KGE mask in ROP field, 

4-5 to 4-6 

FIND operation, 5-52 
GET operation, 5-64 
summary, 6-134 
value, 6-115 
RB$KGT mask in ROP field, 
4-5 to 4-6 

FIND operation, 5-52 

GET operation, 5-64 

summary, 6-135 

value, 6-115 
RB$LOA mask in ROP field 

PUT operation, 5-92, 5-96 

summary, 6-136 

UPDATE operation, 5-124 

value, 6-115 
RB$LOC mask in ROP field, 4-7 

CONNECT operation, 5-6 

GET operation, 5-61, 5-64, 
5-68 

PUT operation, 5-92 
summary, 6-137 
value, 6-115 
RB$MAS mask in ROP field 



PUT operation, 5-92 

summary, 6-138 

value, 6-115 
RB$RFA code in RAC field, 4-6 

FIND operation, 5-54 

GET operation, 5-67 

value, 6-115 
RB$SEQ code in RAC field, 4-4 

FIND operation, 5-49 

GET operation, 5-60 

PUT operation, 5-91 

value, 6-115 
RB$UIF mask in ROP field, 4-4 

PUT operation, 5-92, 5-96 

summary, 6-139 

value, 6-115 
RBF field in RAB, 4-7, 4-13 

CONNECT operation, 5-7 

GET operation, 5-61, 5-65, 
5-68 

offset, 6-115 

PUT operation, 5-92 to 5-93, 
5-95 

READ operation, 5-99, 5-101 

summary, 6-128 

UPDATE operation, 5-124 

WRITE operation, 5-127, 5-129 
RDT field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-20 
READ operation, 4-14 

$READ macro 

sequential access, 5-98 
VBN access, 5-100 
Readable-block context, 4-12 
Record 

access mode 

See RAC field in RAB 

blocked 

See FB$BLK mask in RAT field 
buffer address 

See RBF field in RAB 
deleting 

fast 

See RB$FDL mask in ROP field 

See DELETE operation 
fast deletion 

See RB$FDL mask in ROP field 
format 

See RFM field in FAB 
locat i ng 

See FIND operation 
longest 

See LRL field in FAB 
reading 

See GET operation 
replacing 

See UPDATE operation 
size 

See RSZ field in RAB 
update existing 

See RB$UIF mask in ROP field 
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writing 

See PUT operation 
Record access block 

See RAB field in RAB 
Record access mode, 4-4 
Record context, 4-3 
Record file address 

See RFA field in RAB 
Record length 

longest 

See LRL field in FAB 

max imum 

See MRL field in FAB 
Record number 

maximum 

See MRN field in FAB 
Record operation, 4-9 
Record operation macro 

$DELETE, 5-25 

$F IND , 5-49, 5-51, 5-54 

$GET , 5-60, 5-63, 5-67 

$PUT, 5-91, 5-95 

$TRUNCATE, 5-122 

$UPDATE, 5-124 

declaring, C-3 
Record processing, 4-3 
Record stream, 4-3 
Record-oriented device 

See FB$REC mask in DEV field 
Record-output characteristic 

See RAT field in FAB 
REF field in KEY block, 2-14 

CLOSE operation, 5-3 

CREATE operation, 5-9, 5-18 

DISPLAY operation, 5-30 

ENTER operation, 5-35 

ERASE operation, 5-40 

EXTEND operation, 5-46 

offset, 6-67 

OPEN operation, 5-73 to 5-74 

PARSE operation, 5-86 

REMOVE operation, 5-102 

RENAME operation, 5-108 

SEARCH operation, 5-116 

summary, 6-90 
REL argument to ORG$ macro, 2-3 
Relative file 

declaring with ORG$ macro, 2-3 
Relative file organization 

See FB$REL code 
Relative record number 

See BKT field in RAB 
Remote operation 

P/OS, D-3 
REMOVE operation, 3-6 

$REMOVE macro, 5-102 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
RENAME operation, 3-6 

$RENAME macro, 5-108 

BDB requirement, 2-8 



I/O buffer requirement, 2-7 

IFAB requirement, 2-5 

wildcard loop, 3-10 to 3-11 
nonselective, 3-11 
selective, 3-12 
Resultant string 

See RSA field in NAM block 
Retrieval pointer count 

See RTV field in FAB 
Return 

operation, from, 2-15 
Return from completion handler, 

2-20 
Revision date 

See RDT field in DAT block 
Revision number 

See RVN field in DAT block 
REWIND operation 

$REWIND macro, 5-114 

record stream, 4-9 
RFA field in RAB, 4-6 

CONNECT operation, 5-7 

FIND operation, 5-50, 5-52, 
5-54 

GET operation, 5-61, 5-65, 

5-67 
offset, 6-115 
PUT operation, 5-93, 5-96 
READ operation, 5-99, 5-101 
summary, 6-129 

WRITE operation, 5-128, 5-130 
RFA record access 

See RB$RFA code in RAC field 
RFM field in FAB 

CREATE operation, 5-11 

offset, 6-23 

OPEN operation, 5-78 

summary, 6-61 
RHB field in RAB, 4-7 

GET operation, 5-61, 5-64, 
5-68 

offset, 6-115 

PUT operation, 5-92, 5-96 

summary, 6-130 

UPDATE operation, 5-124 
RMSMAC.MLB macro library, 2-22 

RSTS/E, D-3 
ROP field in RAB, 4-1, 

4-4 to 4-7 

CONNECT operation, 5-6 to 5-7 
DELETE operation, 5-25 
DISCONNECT operation, 5-27 
FIND operation, 5-49, 

5-51 to 5-52, 5-54 
FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-60 to 5-61, 

5-63 to 5-64, 5-67 to 5-68 
NXTVOL operation, 5-70 
offset, 6-115 

PUT operation, 5-91 to 5-92, 

5-95 to 5-96 
READ operation, 5-98, 5-100 
REWIND operation, 5-114 
SPACE operation, 5-120 
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summary 



RB$ASY 


mask , 


6-131 


RB$EOF 


mask , 


6-132 


RB$FDL 


mask , 


6-133 


RB$KGE 


mask , 


6-134 


RB$KGT 


mask , 


6-135 


RB$LOA 


mask , 


6-136 


RB$LOC 


mask , 


6-137 


RB$MAS 


mask , 


6-138 


RB$UIF 


mask , 


6-139 


TRUNCATE 


operation, 5-122 


UPDATE operation, 5-124 



WRITE operation, 5-127, 5-129 
RRN 

See BKT field in RAB 
RSA field in NAM block, 3-10 

offset, 6-94 

SEARCH operation, 5-116 

summary, 6-103 
RSL field in NAM block 

CREATE operation, 5-21 

ENTER operation, 5-38 

ERASE operation, 5-43 

offset, 6-94 

OPEN operation, 5-81 

PARSE operation, 5-87 

REMOVE operation, 5-105 

RENAME operation, 5-112 

SEARCH operation, 
5-116 to 5-117 

summary, 6-104 
RSS field in NAM block 

offset, 6-94 

SEARCH operation, 5-116 

summary, 6-105 
RSTS/E RMS-11 

contrasted with PRO/RMS-11, 
D-l 

contrasted with RSX-11 RMS-11, 
D-3 

RSX-11M/M-PLUS RMS-11 

contrasted with PRO/RMS-11, 
D-3 

contrasted with RSTS/E RMS-11, 
D-3 

RSZ field in RAB, 4-7, 4-13 

GET operation, 5-61, 5-65, 
5-68 

offset, 6-115 

PUT operation, 5-92, 5-95 

READ operation, 5-99, 5-101 

summary, 6-140 

UPDATE operation, 5-124 

WRITE operation, 5-127, 5-129 
RTV field in FAB 

CREATE operation, 5-13 

offset, 6-23 

OPEN operation, 5-75 

RSTS/E, D-3 

summary, 6-62 
RVB field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-91 



RVN field in DAT block 

DISPLAY operation, 5-32 

offset, 6-14 

OPEN operation, 5-81 

RSTS/E, D-4 

summary, 6-21 
RVN field in NAM block 

RSX-11, D-4 

SEARCH operation 

$SEARCH macro, 5-116 

BDB requirement, 2-8 

I/O buffer requirement, 2-7 

I FAB requirement, 2-5 

wildcard loop, 3-10 
explicit, 3-12 
implicit, 3-10 to 3-11 
SEQ argument to ORG$ macro, 2-3 
Sequential block access 

See BKT field in RAB 
Sequential device 

See FB$SQD mask in DEV field 
Sequential file 

declaring with ORG$ macro, 2-3 
Sequential file organization 

See FB$SEQ code 
Sequential record access 

See RB$SEQ code in RAC field 
Shared access 

See SHR field in FAB 
SHR field in FAB 

CREATE operation, 5-14 

offset, 6-22 

OPEN operation, 5-75 

READ operation, 5-99, 5-101 

summary, 6-63 

WRITE operation, 5-127, 5-129 
Single-directory device 

See FB$SDI mask in DEV field 
SIZ field in KEY block 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-80 

summary, 6-92 
SIZ0 field in KEY block 

offset, 6-68 
SIZ1 field in KEY block 

offset, 6-68 
SIZ2 field in KEY block 

offset, 6-68 
SIZ3 field in KEY block 

offset, 6-68 
SIZ4 field in KEY block 

offset, 6-68 
SIZ5 field in KEY block 

offset, 6-68 
SIZ6 field in KEY block 

offset, 6-68 
SIZ7 field in KEY block 

offset, 6-68 
SPACE operation, 4-14 

$SPACE macro, 5-120 
Stream, 4-2 

connect i ng 
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See CONNECT operation 

disconnecting 

See DISCONNECT operation 

internal identifier 
See ISI field in RAB 

unlocking bucket 
See FREE operation 

writing buffers 

See FLUSH operation 
Stream context 

advancing to next volume 
See NXTVOL operation 

rewinding 

See REWIND operation 
Stream operation 

block stream, 4-13 

record stream, 4-8 
Stream operation macro 

$CONNECT, 5-6 

$DISCONNECT, 5-27 

$FLUSH, 5-56 

$FREE, 5-58 

$NXTVOL, 5-70 

$REWIND, 5-114 

$WAIT, 5-126 

declaring, C-3 
Stream record format 

See FB$STM code in RFM field 
String key 

See XB$STG mask in DTP field 
STS field in FAB, 2-15, 3-5 

CLOSE operation, 5-4 

CREATE operation, 5-21 

DISPLAY operation, 5-32 

ENTER operation, 5-38 

ERASE operation, 5-43 

EXTEND operation, 5-47 

offset, 6-22 

OPEN operation, 5-82 

PARSE operation, 5-89 

REMOVE operation, 5-105 

RENAME operation, 5-112 

SEARCH operation, 5-118 

summary, 6-64 
STS field in RAB, 2-15, 4-2 

CONNECT operation, 5-8 

DELETE operation, 5-26 

DISCONNECT operation, 5-27 

FIND operation, 5-50, 5-53, 
5-55 

FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-62, 5-65, 
5-68 

NXTVOL operation, 5-70 
offset, 6-115 
PUT operation, 5-93, 5-97 
READ operation, 5-99, 5-101 
REWIND operation, 5-115 
SPACE operation, 5-120 
summary, 6-141 
TRUNCATE operation, 5-122 
UPDATE operation, 5-125 
WRITE operation, 5-128, 5-130 
STV field in FAB, 2-15, 3-5 



CLOSE operation, 5-4 
CREATE operation, 5-21 
DISPLAY operation, 5-32 
ENTER operation, 5-38 
ERASE operation, 5-43 
EXTEND operation, 5-47 
offset, 6-22 
OPEN operation, 5-82 
PARSE operation, 5-89 
REMOVE operation, 5-105 
RENAME operation, 5-112 
SEARCH operation, 5-118 
summary, 6-65 
STV field in RAB, 2-15, 4-2 
CONNECT operation, 5-8 
DELETE operation, 5-26 
DISCONNECT operation, 5-27 
FIND operation, 5-50, 5-53, 
5-55 

FLUSH operation, 5-56 
FREE operation, 5-58 
GET operation, 5-62, 5-65, 
5-68 

NXTVOL operation, 5-70 

offset, 6-115 

PUT operation, 5-93, 5-97 

READ operation, 5-99, 5-101 

REWIND operation, 5-115 

SPACE operation, 5-120 

summary, 6-142 

TRUNCATE operation, 5-122 

UPDATE operation, 5-125 

WRITE operation, 5-128, 5-130 
SU$-family symbol 

declaring, C-3 

value, A-l 
Success 

handler, 2-18 
SUM block 

chaining to FAB, 2-13 

declaring, 2-9 

initializing, 2-10 

summary, 6-145 
Summary XAB 

See SUM block 
Supersession 

See FB$SUP mask in FOP field 
Symbol-declaration macro, 2-2 
SYN argument to RAB$B macro, 2-8 

RSTS/E, D-4 
Synchronous operation 

See RB$ASY mask in ROP field 

Temporary file 

See FB$TMP mask in FOP field 
Terminal device, 3-1, 5-20, 

5-37, 5-42, 5-77, 5-88, 

5-104, 5-111, 5-117 

See FB$TRM mask in DEV field 
TKS field in KEY block 

DISPLAY operation, 5-31 

offset, 6-68 

OPEN operation, 5-81 

summary, 6-93 
TRUNCATE operation, 4-11 
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$TRUNCATE macro, 5-122 

UBF field in RAB, 4-7, 4-13 

CONNECT operation, 5-6 

GET operation, 5-61, 5-64, 
5-67 

offset, 6-115 

PUT operation, 5-92, 5-96 

READ operation, 5-98, 5-100 

summary, 6-143 
Undefined record format 

See FB$UDF code in RFM field 
Unit-record device, 3-2, 5-20, 

5-37, 5-43, 5-77, 5-88, 

5-104, 5-111, 5-117 
UPD argument to ORG$ macro, 2-3 
UPDATE operation, 4-11 

$UPDATE macro, 5-124 

declaring with ORG$ macro, 2-3 
User buffer 

address 

See UBF field in RAB 

size 

See USZ field in RAB 
USZ field in RAB, 4-7, 4-13 
CONNECT operation, 5-6 
GET operation, 5-61, 5-64, 

5-67 
offset, 6-115 
PUT operation, 5-92, 5-96 
READ operation, 5-98, 5-100 
summary, 6-144 

Variable-length record format 

See FB$VAR code in RFM field 
VBN 

See BKT field in RAB 
VBN access 

See BKT field in RAB 
VFC carriage control 

See FB$PRN mask in RAT field 
VFC header buffer address 

See RHB field in RAB 
VFC record format 

See FB$VFC code in RFM field 
Virtual block number 

See BKT field in RAB 
Vol ume 

advancing to next 

See NXTVOL operation 

WAIT operation 

$WAIT macro, 5-126 

block stream, 4-14 

record stream, 4-9 
WCC field in NAM block 

offset, 6-94 

PARSE operation, 5-87 

SEARCH operation, 5-116, 5-118 

summary, 6-106 
WDI field in NAM block 

offset, 6-94 

PARSE operation, 5-87 

SEARCH operation, 5-116, 5-118 

summary, 6-107 



Wi ldcard 

directory context 

See WDI field in NAM block 
file context 

See WCC field in NAM block 
operation 

See NB$WCH mask in FNB field 
Wildcard loop, 3-9 
Writable-block context, 4-12 
WRITE operation, 4-14 
$WRITE macro 

sequential access, 5-127 
VBN access, 5-129 

X$-family macro, 2-10 
declaring 

ALL block, C-3 
DAT block, C-3 
KEY block, C-3 
PRO block, C-3 
SUM block, C-3 

XAB 

chaining to FAB, 2-13 

See also ALL block 

See also DAT block 

See also KEY block 

See also PRO block 

See also SUM block 
XAB field in FAB 

chaining XABs to FAB, 2-13 

CLOSE operation, 5-3 

CREATE operation, 5-9 

DISPLAY operation, 5-29 

ENTER operation, 5-35 

ERASE operation, 5-40 

EXTEND operation, 5-46 

offset, 6-24 

OPEN operation, 5-73 

PARSE operation, 5-86 

REMOVE operation, 5-102 

RENAME operation, 5-108 

SEARCH operation, 5-116 

summary, 6-66 
XAB$B macro, 2-8 to 2-9, C-3 
XAB$BT macro, C-4 
XAB$E macro, 2-10 

declaring, C-3 
XABOF$ macro, C-4 
XB$-family symbol 

declaring 

ALL block, C-3 to C-4 
DAT block, C-3 to C-4 
KEY block, C-3 to C-4 
PRO block, C-3 to C-4 
SUM block, C-3 to C-4 
XAB, C-4 
XB$ALL code in COD field, 2-8 

summary, 6-10 

value, 6-2 
XB$BN2 code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$BN4 code in DTP field 
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CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$CHG mask in FLG field 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

summary, 6-76 

value, 6-67 
XB$CTG mask in AOP field 

CREATE operation, 5-18 

EXTEND operation, 5-47 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-6 

value, 6-2 
XB$CYL mask in ALN field 

RSTS/E, D-3 to D-4 
XB$DAT code in COD field, 2-8 

summary, 6-17 

value, 6-14 
XB$DTL code in BLN field 

summary, 6-15 

value, 6-14 
XB$DUP mask in FLG field 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

summary, 6-77 

value, 6-67 
XB$HRD mask in AOP field 

CREATE operation, 5-17 

EXTEND operation, 5-47 

of ALL block 
RSX-11, D-4 

OPEN operation, 5-79 

RSTS/E, D-4 

summary, 6-7 

value, 6-2 
XB$IN2 code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$IN4 code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$INI mask in FLG field 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$ KEY code in COD field, 2-8 

summary, 6-70 

value, 6-67 
XB$ KYL code in BLN field 

summary, 6-69 

value, 6-67 
XB$LAL code in BLN field 

summary, 6-9 

value, 6-2 
XB$LBN mask in ALN field 

CREATE operation, 5-17 



EXTEND operation, 5-47 

RSTS/E, D-3 to D-4 

value, 6-2 
XB$NUL mask in FLG field 

CREATE operation, 5-19 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

summary, 6-78 

value, 6-67 
XB$PAC code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$PRL code in BLN field 

summary, 6-109 

value, 6-108 
XB$PRO code in COD field, 2-9 

summary, 6-110 

value, 6-108 
XB$SML code in BLN field 

summary, 6-146 

value, 6-145 
XB$STG code in DTP field 

CREATE operation, 5-18 

DISPLAY operation, 5-31 

OPEN operation, 5-80 

value, 6-67 
XB$SUM code in COD field, 2-9 

summary, 6-147 

value, 6-145 
XB$VBN mask in ALN field 

CREATE operation, 5-17 

EXTEND operation, 5-47 

RSTS/E, D-3 to D-4 

value, 6-2 
XBAOF$ macro, C-4 
XBDOF$ macro, C-4 
XBKOF$ macro, C-4 
XBPOF$ macro, C-4 
XBSOF$ macro, C-4 
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